Merge pull request #88 from jkaninda/docs

update readme

.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: jkaninda

.github/workflows/tests.yml

@@ -6,6 +6,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Build Docker Image
+        run: |
+            docker buildx build -f src/docker/Dockerfile --build-arg phpVersion=8.4 -t ${{ vars.BUILDKIT_IMAGE }}:latest --load .
+      - name: Verify Docker images
+        run: |
+            docker images
       - name: Create Laravel project
         run: |
          composer create-project laravel/laravel laravel

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jonas Kaninda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,8 @@
+### 🐳 **Docker Image: Laravel PHP-FPM**  
+
+A **ready-to-use container** designed for running PHP-based applications, including Laravel microservices.
+This Docker image comes with **PHP-FPM**, offering a robust foundation for your projects with built-in support for essential extensions and configurations.
+
 [![Build](https://github.com/jkaninda/laravel-php-fpm/actions/workflows/build.yml/badge.svg)](https://github.com/jkaninda/laravel-php-fpm/actions/workflows/build.yml)
 [![Tests](https://github.com/jkaninda/laravel-php-fpm/actions/workflows/tests.yml/badge.svg)](https://github.com/jkaninda/laravel-php-fpm/actions/workflows/tests.yml)
 ![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/jkaninda/laravel-php-fpm?style=flat-square)
@@ -9,17 +14,26 @@
   </a>
   </p>
 
-# Laravel PHP-FPM Docker image
+#### **Features**  
+- **PHP Application Support**: Optimized to run Laravel or any PHP-based applications.  
+- **Integrated Extensions**:  
+  - **Database**: MySQL and PostgreSQL.  
+  - **Caching**: Redis and Memcached.  
+  - **Messaging**: Kafka for event-driven architecture.  
+  - **Task Scheduling**: Laravel Scheduler and Cron jobs support.  
+- **Custom Configuration**: Pre-configured with sensible defaults, allowing seamless customization.  
+- **Event Handling**: Support for advanced event-driven processes.  
+- **Optimized for Microservices**: Built with modern PHP microservices in mind.  
 
-> 🐳 Full Docker image for a PHP-FPM container created to run Laravel or any php based applications.
+This image is ideal for developers looking for a streamlined, high-performance solution to deploy PHP applications with essential tools already integrated.
 
-> PHP Microservices ready Docker container image.
 
+## Links:
 - [Docker Hub](https://hub.docker.com/r/jkaninda/laravel-php-fpm)
 - [Github](https://github.com/jkaninda/laravel-php-fpm)
+---
 
-
+## **Supported PHP Versions**
-## PHP Version:
 - 8.4  
 - 8.3  
 - 8.2  
@@ -27,97 +41,48 @@
 - 8.0  
 - 7.4  
 - 7.2  
-## Specifications:
 
-* Composer
+---
-* OpenSSL PHP Extension
-* XML PHP Extension
-* PDO PHP Extension
-* PDO Mysql
-* PDO Pgsql
-* Rdkafka PHP Extension
-* Redis PHP Extension
-* Mbstring PHP Extension
-* PCNTL PHP Extension
-* ZIP PHP Extension
-* GD PHP Extension
-* BCMath PHP Extension
-* Memcached
-* Opcache
-* Laravel Cron Job
-* Laravel Schedule
-* Laravel Envoy
-* Supervisord
-* Node
-* NPM
 
-## Simple docker-compose usage:
+## **Specifications**
 
-```yml
+### **PHP Extensions**
-version: '3'
+- Composer  
+- OpenSSL  
+- XML  
+- PDO (MySQL and PostgreSQL)  
+- Rdkafka  
+- Redis  
+- Mbstring  
+- PCNTL  
+- ZIP  
+- GD  
+- BCMath  
+- Memcached  
+- Opcache  
+
+### **Additional Features**
+- Laravel Cron Jobs  
+- Laravel Scheduler  
+- Supervisord  
+- Node.js and NPM  
+
+---
+
+## **Getting Started**
+
+### **Simple Docker-Compose Example**
+```yaml
 services:
   php-fpm:
     image: jkaninda/laravel-php-fpm:latest
     container_name: php-fpm
     restart: unless-stopped
-        user: www-data #Use www-data user for production usage     
+    user: www-data # For production
     volumes:
-        #Project root
-            - ./src:/var/www/html
-        networks:
-            - default #if you're using networks between containers
-
-```
-## Docker:
-### Run
-```sh
- docker compose up -d
-```
-### Create Laravel project
-```sh
-docker compose exec php-fpm composer create-project --prefer-dist laravel/laravel .
-```
-### Artisan generate key
-```sh
-docker compose exec php-fpm php artisan key:generate
-```
-### Storage link
-```sh
-docker compose exec php-fpm php artisan storage:link
-```
-### Fix permissions
-```sh
-docker compose exec php-fpm chmod -R 777 storage bootstrap/cache
-```
-### Laravel migration
-```sh
- docker compose exec php-fpm php artisan migrate
-```
-### 
-```sh
-docker exec -it php-fpm bash
-
-```
-
-## Configurations
-
-- Supervisor config folder: /etc/supervisor/conf.d/
-- PHP ini config foler /usr/local/etc/php/conf.d/
-
-## Example Laravel-php-fpm with nginx:
-### docker-compose.yml
-```yml
-services:
-    php-fpm:
-        image: jkaninda/laravel-php-fpm
-        container_name: php-fpm
-        restart: unless-stopped     
-        volumes:
-        #Project root
       - ./:/var/www/html
     networks:
-            - default #if you're using networks between containers
+      - default
-    #Nginx server
   nginx-server:
      image: jkaninda/nginx-fpm:alpine
      container_name: nginx-server
@@ -132,63 +97,63 @@ services:
        - PHP_FPM_HOST=php-fpm:9000 
      networks:
       - default
-
-```
-## Simple Nginx config file content
-### default.conf
-
-```conf
-
-server {
-    listen 80;
-    index index.php index.html;
-    error_log  /var/log/nginx/error.log;
-    access_log /var/log/nginx/access.log;
-    ##Public directory
-    root /var/www/html/public;
-    location ~ \.php$ {
-        try_files $uri =404;
-        fastcgi_split_path_info ^(.+\.php)(/.+)$;
-        ## PHP FPM ( php-fpm:9000 ) or [servicename:9000]
-        fastcgi_pass php-fpm:9000;
-        fastcgi_index index.php;
-        include fastcgi_params;
-        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
-        fastcgi_param PATH_INFO $fastcgi_path_info;
-        
-    }
-    client_max_body_size 15M;
-    server_tokens off;
-
-     # Hide PHP headers 
-    fastcgi_hide_header X-Powered-By; 
-    fastcgi_hide_header X-CF-Powered-By;
-    fastcgi_hide_header X-Runtime;
-
-    location / {
-        try_files $uri $uri/ /index.php?$query_string;
-        gzip_static on;
-    }
-}
 ```
 
-## Advanced Laravel-php-fpm with nginx:
+### **Basic Commands**
-### docker-compose.yml
+- **Start Containers**  
-```yml
+  ```sh
+  docker compose up -d
+  ```
+
+- **Create a Laravel Project**  
+  ```sh
+  docker compose exec php-fpm composer create-project --prefer-dist laravel/laravel .
+  ```
+
+- **Generate Application Key**  
+  ```sh
+  docker compose exec php-fpm php artisan key:generate
+  ```
+
+- **Create Storage Symlink**  
+  ```sh
+  docker compose exec php-fpm php artisan storage:link
+  ```
+
+- **Fix Permissions**  
+  ```sh
+  docker compose exec php-fpm chmod -R 777 storage bootstrap/cache
+  ```
+
+- **Run Laravel Migrations**  
+  ```sh
+  docker compose exec php-fpm php artisan migrate
+  ```
+
+- **Access the Container Shell**  
+  ```sh
+  docker exec -it php-fpm bash
+  ```
+
+---
+
+## **Advanced Usage with Nginx**
+
+### **Docker-Compose with Nginx**
+Example of using a custom nginx config:
+
+```yaml
+version: '3'
 services:
   php-fpm:
     image: jkaninda/laravel-php-fpm
     container_name: php-fpm
     restart: unless-stopped
     volumes:
-        #Project root
       - ./:/var/www/html
-            - ~/.ssh:/root/.ssh # If you use private CVS
+    networks:
-            - ./php.ini:/usr/local/etc/php/conf.d/php.ini # Optional, your custom php init file
+      - default
-        environment:
+
-           - APP_ENV=development # Optional, or production
-           #- LARAVEL_PROCS_NUMBER=1 # Optional, Laravel queue:work process number
-    #Nginx server
   nginx-server:
     image: nginx:alpine
     container_name: nginx-server
@@ -198,46 +163,68 @@ services:
     volumes:
       - ./:/var/www/html
       - ./default.conf:/etc/nginx/conf.d/default.conf
+    environment:
+      - DOCUMENT_ROOT=/var/www/html/public
+      - CLIENT_MAX_BODY_SIZE=20M
+      - PHP_FPM_HOST=php-fpm:9000
     networks:
       - default
-volumes:
- storage-data: 
 ```
 
-## Docker run
+### **Nginx Configuration (default.conf)**
-```sh
- docker compose up -d
 
+```conf
+server {
+    listen 80;
+    index index.php index.html;
+    root /var/www/html/public;
+
+    location ~ \.php$ {
+        try_files $uri =404;
+        fastcgi_split_path_info ^(.+\.php)(/.+)$;
+        fastcgi_pass php-fpm:9000;
+        fastcgi_index index.php;
+        include fastcgi_params;
+        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+        fastcgi_param PATH_INFO $fastcgi_path_info;
+    }
+
+    location / {
+        try_files $uri $uri/ /index.php?$query_string;
+        gzip_static on;
+    }
+
+    client_max_body_size 15M;
+    server_tokens off;
+    fastcgi_hide_header X-Powered-By;
+}
 ```
-## Build from base
 
-Dockerfile
+---
+
+## **Custom Build**
+
+### **Dockerfile Example**
 ```Dockerfile
 FROM jkaninda/laravel-php-fpm:8.3
-# Copy laravel project files
+# Copy Laravel project files
 COPY . /var/www/html
-# Storage Volume
 VOLUME /var/www/html/storage
-
 WORKDIR /var/www/html
 
-# Custom cache invalidation / optional
-#ARG CACHEBUST=1
-# Run composer install / Optional
-#RUN composer install
 # Fix permissions
 RUN chown -R www-data:www-data /var/www/html
 
+USER www-data
 ```
-## Supervisord
-### Add supervisor process in
 
-> /etc/supervisor/conf.d/
+---
 
-In case you want to execute and maintain a task or process with supervisor.
+## **Supervisord Integration**
 
-Find below an example with Apache Kafka, when you want to maintain a consumer process.
+### **Adding Custom Supervisor Processes**
-### Example:
+Place configurations in `/etc/supervisor/conf.d/`.  
+Example Kafka consumer process:  
 ```conf
 [program:kafkaconsume-worker]
 process_name=%(program_name)s_%(process_num)02d
@@ -250,21 +237,50 @@ redirect_stderr=true
 stdout_logfile=/var/www/html/storage/logs/kafka.log
 ```
 
-### Custom php.ini
+---
-> /var/www/html/conf/php/php.ini
+
+## **Custom PHP Configurations**
+Place your custom `php.ini` file at:  
+```
+/usr/local/etc/php/conf.d/
+```
+
+---
+
+## **Storage Permissions Fix**
+If you encounter permission issues, run:  
 
-### Storage permision issue
 ```sh
 docker compose exec php-fpm /bin/bash
- ```
-
-```sh
 chown -R www-data:www-data /var/www/html
+chmod -R 775 /var/www/html/storage
 ```
+---
 
-> chmod -R 775 /var/www/html/storage
+### Explore Another Project: Goma Gateway
 
+Are you building a microservices architecture?
+Do you need a powerful yet lightweight API Gateway or a high-performance reverse proxy to secure and manage your services effortlessly?
 
-> P.S. please give a star if you like it :wink:
+Check out my other project — **[Goma Gateway](https://github.com/jkaninda/goma-gateway)**.
 
+**Goma Gateway** is a high-performance, declarative API Gateway built for modern microservices. It comes with a rich set of built-in middleware, including:
+
+* Basic, JWT, OAuth2, LDAP, and ForwardAuth authentication
+* Caching and rate limiting
+* Bot detection
+* Built-in load balancing
+* Simple configuration with minimal overhead
+* ...and more!
+
+**Protocol support:** REST, GraphQL, gRPC, TCP, and UDP
+
+**Security:** Automatic HTTPS via Let’s Encrypt or use your own TLS certificates
+
+Whether you're managing internal APIs or exposing public endpoints, **Goma Gateway** helps you do it efficiently, securely, and with minimal complexity.
+
+---
+
+### ⭐️ **Support the Project**  
+If this project helped you, do not skip on giving it a star. Thanks!
 

compose.yaml

@@ -0,0 +1,29 @@
+services:
+    php-fpm:
+        image: jkaninda/laravel-php-fpm
+        container_name: php-fpm
+        restart: unless-stopped 
+        user: www-data #Use www-data user  production usage
+        volumes:
+        #Project root
+            - ./:/var/www/html
+        networks:
+            - web #if you're using networks between containers
+    #Nginx server
+    nginx-server:
+     image: jkaninda/nginx-fpm:alpine
+     container_name: nginx-server
+     restart: unless-stopped
+     ports:
+      - 80:80
+     volumes:
+      - ./:/var/www/html
+     environment:
+       - DOCUMENT_ROOT=/var/www/html/public
+       - CLIENT_MAX_BODY_SIZE=20M
+       - PHP_FPM_HOST=php-fpm:9000 
+     networks:
+      - web
+networks:
+  web:
+   external: false

src/entrypoint.sh

@@ -1,34 +1,45 @@
 #!/bin/bash
 
+set -e
+
+# Logging functions
+log() {
+    local level=$1
+    shift
+    { set +x; } 2> /dev/null
+    echo "[$level] $@"
+}
+
+info() {
+    log "INFO" "$@"
+}
+
+warning() {
+    log "WARNING" "$@"
+}
+
+fatal() {
+    log "ERROR" "$@" >&2
+    exit 1
+}
+
+# Banner
 echo ""
 echo "***********************************************************"
 echo "   Starting LARAVEL PHP-FPM Container                      "
 echo "***********************************************************"
 
-set -e
+# Check if the artisan file exists
-info() {
+ARTISAN_PATH="/var/www/html/artisan"
-    { set +x; } 2> /dev/null
+if [[ -f "$ARTISAN_PATH" ]]; then
-    echo '[INFO] ' "$@"
+    info "Artisan file found, creating Laravel supervisor config..."
-}
+
-warning() {
+    # Create Laravel Supervisor config
-    { set +x; } 2> /dev/null
+    SUPERVISOR_TASK="/etc/supervisor/conf.d/laravel-worker.conf"
-    echo '[WARNING] ' "$@"
+    cat > "$SUPERVISOR_TASK" <<EOF
-}
-fatal() {
-    { set +x; } 2> /dev/null
-    echo '[ERROR] ' "$@" >&2
-    exit 1
-}
-## Check if the artisan file exists
-if [ -f /var/www/html/artisan ]; then
-    info "Artisan file found, creating laravel supervisor config..."
-    ##Create Laravel Scheduler process
-    TASK=/etc/supervisor/conf.d/laravel-worker.conf
-    touch $TASK
-    cat > "$TASK" <<EOF
 [program:Laravel-scheduler]
 process_name=%(program_name)s_%(process_num)02d
-    command=/bin/sh -c "while [ true ]; do (php /var/www/html/artisan schedule:run --verbose --no-interaction &); sleep 60; done"
+command=/bin/sh -c "while true; do php $ARTISAN_PATH schedule:run --verbose --no-interaction & sleep 60; done"
 autostart=true
 autorestart=true
 numprocs=1
@@ -38,7 +49,7 @@ if [ -f /var/www/html/artisan ]; then
 
 [program:Laravel-worker]
 process_name=%(program_name)s_%(process_num)02d
-    command=php /var/www/html/artisan queue:work --sleep=3 --tries=3
+command=php $ARTISAN_PATH queue:work --sleep=3 --tries=3
 autostart=true
 autorestart=true
 numprocs=$LARAVEL_PROCS_NUMBER
@@ -46,18 +57,23 @@ if [ -f /var/www/html/artisan ]; then
 redirect_stderr=true
 stdout_logfile=/var/log/laravel_worker.log
 EOF
-info  "Laravel supervisor config created"
+
+    info "Laravel supervisor config created at $SUPERVISOR_TASK"
 else
-    info "artisan file not found"
+    info "Artisan file not found at $ARTISAN_PATH"
 fi
 
-## Check if php.ini file exists
+# Check if custom php.ini file exists
-if [ -f /var/www/html/conf/php/php.ini ]; then
+PHP_INI_SOURCE="/var/www/html/conf/php/php.ini"
-    cp /var/www/html/conf/php/php.ini $PHP_INI_DIR/conf.d/
+PHP_INI_TARGET="$PHP_INI_DIR/conf.d/php.ini"
-    info "Custom php.ini file found and copied in  $PHP_INI_DIR/conf.d/"
+
+if [[ -f "$PHP_INI_SOURCE" ]]; then
+    cp "$PHP_INI_SOURCE" "$PHP_INI_TARGET"
+    info "Custom php.ini file found and copied to $PHP_INI_TARGET"
 else
-    info "Custom php.ini file not found"
+    info "Custom php.ini file not found at $PHP_INI_SOURCE"
-    info "If you want to add a custom php.ini file, you add it in /var/www/html/conf/php/php.ini"
+    info "To use a custom php.ini file, place it at $PHP_INI_SOURCE"
 fi
 
+# Start Supervisor
 supervisord -c /etc/supervisor/supervisord.conf

tests/compose.yaml

@@ -12,7 +12,7 @@ services:
       ports:
        - 3306:3306
     php-fpm:
-        image: jkaninda/laravel-php-fpm
+        image: jkaninda/laravel-php-fpm:latest
         container_name: php-fpm
         restart: unless-stopped
         #user: www-data #Use www-data user  production usage

version

@@ -0,0 +1 @@
+8.4.7