polish nginx-fpm for production

Author: rw4lll

example-app/entrypoint.sh

@@ -1,12 +1,29 @@
 #!/bin/sh
 set -e
 
-# Check if the storage directory is empty (initial start)
+# Initialize storage directory if empty
+# -----------------------------------------------------------
+# If the storage directory is empty, copy the initial contents
+# and set the correct permissions.
+# -----------------------------------------------------------
 if [ ! "$(ls -A /var/www/storage)" ]; then
   echo "Initializing storage directory..."
   cp -R /var/www/storage-init/. /var/www/storage
   chown -R www-data:www-data /var/www/storage
 fi
 
+# Run Laravel migrations
+# -----------------------------------------------------------
+# Ensure the database schema is up to date.
+# -----------------------------------------------------------
+php artisan migrate --force
+
+# Clear and cache configurations
+# -----------------------------------------------------------
+# Improves performance by caching config and routes.
+# -----------------------------------------------------------
+php artisan config:cache
+php artisan route:cache
+
 # Run the default command
 exec "$@"

example-app/routes/web.php

@@ -6,3 +6,55 @@
     Log::info('Welcome page visited');
     return view('welcome');
 });
+
+Route::get('/health', function () {
+    $status = [];
+
+    // Check Database Connection
+    try {
+        DB::connection()->getPdo();
+        // Optionally, run a simple query
+        DB::select('SELECT 1');
+        $status['database'] = 'OK';
+    } catch (\Exception $e) {
+        $status['database'] = 'Error';
+    }
+
+    // Check Redis Connection
+    try {
+        Cache::store('redis')->put('health_check', 'OK', 10);
+        $value = Cache::store('redis')->get('health_check');
+        if ($value === 'OK') {
+            $status['redis'] = 'OK';
+        } else {
+            $status['redis'] = 'Error';
+        }
+    } catch (\Exception $e) {
+        $status['redis'] = 'Error';
+    }
+
+    // Check Storage Access
+    try {
+        $testFile = 'health_check.txt';
+        Storage::put($testFile, 'OK');
+        $content = Storage::get($testFile);
+        Storage::delete($testFile);
+
+        if ($content === 'OK') {
+            $status['storage'] = 'OK';
+        } else {
+            $status['storage'] = 'Error';
+        }
+    } catch (\Exception $e) {
+        $status['storage'] = 'Error';
+    }
+
+    // Determine overall health status
+    $isHealthy = collect($status)->every(function ($value) {
+        return $value === 'OK';
+    });
+
+    $httpStatus = $isHealthy ? 200 : 503;
+
+    return response()->json($status, $httpStatus);
+});

production/nginx-fpm/.env.example

@@ -1,23 +1,18 @@
-# Sync user ID and group ID to avoid permission issues
-UID=1000  # Replace with your user ID
-GID=1000  # Replace with your group ID
-
-# Path to your Laravel application
-LARAVEL_APP_PATH=/absolute/path/to/your-laravel-app
+COMPOSE_PROJECT_NAME=laravel-example-production-nginx-fpm
 
 # Nginx configuration
-# The host where Nginx will be accessible.
-NGINX_HOST=localhost
-
 # The port on which Nginx will listen. Typically, this would be port 80.
 NGINX_PORT=80
 
 # PostgreSQL database configuration
 # The name of the database to be used by your Laravel application.
-DB_DATABASE=laravel
+POSTGRES_DATABASE=laravel
 
 # The username for accessing the PostgreSQL database.
-DB_USERNAME=laravel
+POSTGRES_USERNAME=laravel
 
 # The password for accessing the PostgreSQL database.
-DB_PASSWORD=secret
+POSTGRES_PASSWORD=secret
+
+# The port on which the PostgreSQL database will be exposed.
+POSTGRES_PORT=5432

production/nginx-fpm/compose.yaml

@@ -1,17 +1,26 @@
 services:
   web:
-    image: nginx:alpine
     build:
       context: ../../example-app
       dockerfile: ../production/nginx-fpm/nginx/Dockerfile
+    restart: unless-stopped # Automatically restart unless the service is explicitly stopped
     volumes:
-      - laravel-storage:/var/www/storage:ro  # Mount the storage volume (in case you want to use storage:link)
+      # Mount the 'laravel-storage' volume to '/var/www/storage' inside the container.
+      # -----------------------------------------------------------
+      # This volume stores persistent data like uploaded files and cache.
+      # The ':ro' option mounts it as read-only in the 'web' service because Nginx only needs to read these files.
+      # The 'php-fpm' service mounts the same volume without ':ro' to allow write operations.
+      # -----------------------------------------------------------
+      - laravel-storage:/var/www/storage:ro
     networks:
       - laravel
     ports:
+      # Map port 80 inside the container to the port specified by 'NGINX_PORT' on the host machine.
+      # -----------------------------------------------------------
+      # This allows external access to the Nginx web server running inside the container.
+      # For example, if 'NGINX_PORT' is set to '8080', accessing 'http://localhost:8080' will reach the application.
+      # -----------------------------------------------------------
       - "${NGINX_PORT}:80"
-    environment:
-      - NGINX_HOST=${NGINX_HOST}
     depends_on:
       php-fpm:
         condition: service_healthy  # Wait for php-fpm health check
@@ -21,52 +30,61 @@ services:
     build:
       context: ../../example-app
       dockerfile: ../production/nginx-fpm/php-fpm/Dockerfile
+    restart: unless-stopped
     volumes:
       - laravel-storage:/var/www/storage  # Mount the storage volume
-    environment:
-      - APP_NAME=TestApp
-      - APP_KEY=base64:y6S7gjyAO/PVAJMBvJSJUCO8qiz92qvcNAPRKH3hpj4=
-      - APP_DEBUG=true
+    env_file:
+      - ../../example-app/.env
     networks:
       - laravel
     healthcheck:
       test: ["CMD-SHELL", "php-fpm-healthcheck || exit 1"]
       interval: 10s
       timeout: 5s
       retries: 3
-    # The `depends_on` section tells Docker Compose to
-    # start the database before your application.
+    # The 'depends_on' attribute with 'condition: service_healthy' ensures that
+    # this service will not start until the 'postgres' service passes its health check.
+    # This prevents the application from trying to connect to the database before it's ready.
     depends_on:
       postgres:
         condition: service_healthy
 
+  # The 'php-cli' service provides a command-line interface for running Artisan commands and other CLI tasks.
+  # -----------------------------------------------------------
+  # This is useful for running migrations, seeders, or any custom scripts.
+  # It shares the same codebase and environment as the 'php-fpm' service.
+  # -----------------------------------------------------------
   php-cli:
     build:
       context: ../../example-app
       dockerfile: ../production/nginx-fpm/php-cli/Dockerfile
-    tty: true   # Keep the terminal open
-    stdin_open: true  # Keep stdin open to attach to the container
-    environment:
-      - APP_NAME=TestApp
+    tty: true  # Enables an interactive terminal
+    stdin_open: true  # Keeps standard input open for 'docker exec'
+    env_file:
+      - ../../example-app/.env
     networks:
       - laravel
 
   postgres:
     image: postgres:16
-    restart: always
+    restart: unless-stopped
     user: postgres
-    secrets:
-      - db-password
     ports:
-      - "5432:5432"
+      - "${POSTGRES_PORT}:5432"
     environment:
-      - POSTGRES_DB=${DB_DATABASE}
-      - POSTGRES_USER=${DB_USERNAME}
-      - POSTGRES_PASSWORD_FILE=/run/secrets/db-password
+      - POSTGRES_DB=${POSTGRES_DATABASE}
+      - POSTGRES_USER=${POSTGRES_USERNAME}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
     volumes:
       - postgres-data:/var/lib/postgresql/data
     networks:
       - laravel
+    # Health check for PostgreSQL
+    # -----------------------------------------------------------
+    # Health checks allow Docker to determine if a service is operational.
+    # The 'pg_isready' command checks if PostgreSQL is ready to accept connections.
+    # This prevents dependent services from starting before the database is ready.
+    # -----------------------------------------------------------
     healthcheck:
       test: [ "CMD", "pg_isready" ]
       interval: 10s
@@ -75,21 +93,28 @@ services:
 
   redis:
     image: redis:alpine
+    restart: unless-stopped  # Automatically restart unless the service is explicitly stopped
     networks:
       - laravel
+    # Health check for Redis
+    # -----------------------------------------------------------
+    # Checks if Redis is responding to the 'PING' command.
+    # This ensures that the service is not only running but also operational.
+    # -----------------------------------------------------------
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
       interval: 10s
       timeout: 5s
       retries: 3
 
 networks:
+  # Attach the service to the 'laravel' network.
+  # -----------------------------------------------------------
+  # This custom network allows all services within it to communicate using their service names as hostnames.
+  # For example, 'php-fpm' can connect to 'postgres' by using 'postgres' as the hostname.
+  # -----------------------------------------------------------
   laravel:
 
 volumes:
   postgres-data:
   laravel-storage:
-
-secrets:
-  db-password:
-    file: db-password.txt

production/nginx-fpm/db-password.txt

@@ -21,15 +21,21 @@ RUN npm install && npm run build
 FROM nginx:alpine
 
 # Copy custom Nginx configuration
+# -----------------------------------------------------------
+# Replace the default Nginx configuration with our custom one
+# that is optimized for serving a Laravel application.
+# -----------------------------------------------------------
 COPY nginx.conf /etc/nginx/nginx.conf
 
-# Copy Laravel's public assets (from the builder stage)
+# Copy Laravel's public assets from the builder stage
+# -----------------------------------------------------------
+# We only need the 'public' directory from our Laravel app.
+# -----------------------------------------------------------
 COPY --from=builder /var/www/public /var/www/public
 
-# Ensure proper permissions for www-data (Nginx default user)
-#RUN chown -R www-data:www-data /var/www/public
+# Set the working directory to the public folder
+WORKDIR /var/www/public
 
-# Expose port 80
+# Expose port 80 and start Nginx
 EXPOSE 80
-
 CMD ["nginx", "-g", "daemon off;"]

production/nginx-fpm/nginx/Dockerfile

@@ -81,7 +81,13 @@ COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions
 COPY --from=builder /usr/local/etc/php/conf.d/ /usr/local/etc/php/conf.d/
 COPY --from=builder /usr/local/bin/docker-php-ext-* /usr/local/bin/
 
-# Use the default production configuration for PHP runtime arguments
+# Use the recommended production PHP configuration
+# -----------------------------------------------------------
+# PHP provides development and production configurations.
+# Here, we replace the default php.ini with the production
+# version to apply settings optimized for performance and
+# security in a live environment.
+# -----------------------------------------------------------
 RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
 
 # Enable PHP-FPM status page by modifying zz-docker.conf with sed