Laravel Dockerfile Generator

Complete Guide to Laravel Dockerfile and Supervisor Configuration

Docker has revolutionized the way we deploy and manage Laravel applications, providing consistency across development, staging, and production environments. This comprehensive guide covers everything you need to know about creating production-ready Laravel Dockerfiles, configuring Nginx for optimal performance, and setting up Supervisor for process management.

Understanding Laravel Dockerfile Architecture

A well-structured Laravel Dockerfile follows the multi-stage build pattern, which significantly reduces the final image size while maintaining all necessary functionality. The multi-stage approach separates the build process into distinct phases: dependency installation, asset compilation, and production runtime.

The first stage typically handles Node.js dependencies and frontend asset compilation. This stage uses the official Node.js Alpine image, which is lightweight and secure. The second stage manages PHP Composer dependencies, ensuring that only production dependencies are included in the final image. The third and final stage creates the production runtime environment with PHP-FPM, Nginx, and Supervisor.

PHP Extensions and Performance Optimization

Laravel applications require specific PHP extensions to function properly. The most critical extensions include PDO MySQL for database connectivity, MBString for multibyte string handling, XML for data processing, and CType for character type checking. Additional extensions like GD for image manipulation, ZIP for file compression, and CURL for HTTP requests are commonly needed for modern Laravel applications.

Performance optimization in Docker containers involves several key strategies. Opcache configuration is crucial for production environments, as it caches compiled PHP bytecode in memory, significantly reducing execution time. The recommended Opcache settings include enabling the cache, allocating sufficient memory (typically 256MB), and configuring appropriate revalidation frequencies.

opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=4000
opcache.revalidate_freq=2
opcache.fast_shutdown=1
opcache.validate_timestamps=0

Nginx Configuration for Laravel

Nginx serves as the web server and reverse proxy for Laravel applications in Docker containers. A properly configured Nginx setup includes optimized worker processes, efficient connection handling, and comprehensive security headers. The configuration should handle static file serving, PHP-FPM proxying, and implement proper caching strategies.

Security considerations in Nginx configuration include hiding server tokens, implementing security headers like X-Frame-Options and X-Content-Type-Options, and denying access to sensitive directories like storage and bootstrap/cache. Performance optimizations include enabling gzip compression, setting appropriate buffer sizes, and configuring static file caching with proper expiration headers.

Supervisor Process Management

Supervisor is essential for managing multiple processes within a single Docker container. It ensures that critical services like Nginx, PHP-FPM, and Laravel queue workers remain running and automatically restart if they fail. Supervisor configuration includes process definitions, restart policies, logging settings, and user permissions.

Laravel queue workers are particularly important for background job processing. Supervisor can manage multiple queue worker processes, each handling different queue types or priorities. The configuration includes process naming, restart policies, and resource limits to prevent memory leaks and ensure optimal performance.

Laravel Horizon Integration

Laravel Horizon provides a beautiful dashboard and code-driven configuration for Redis queues. When enabled in Docker containers, Horizon manages queue workers automatically, provides real-time monitoring, and handles job balancing across multiple workers. Supervisor configuration for Horizon includes proper user permissions, logging, and graceful shutdown procedures.

Horizon's configuration in Docker environments requires careful attention to Redis connectivity, worker scaling, and memory management. The Supervisor configuration ensures Horizon starts automatically with the container and restarts gracefully during deployments.

Laravel Octane for High Performance

Laravel Octane dramatically improves application performance by keeping the application in memory between requests. When using Octane with Swoole or RoadRunner, the application bootstrap process occurs only once, eliminating the overhead of loading the framework for each request. This results in significantly faster response times and reduced memory usage.

Octane configuration in Docker requires special considerations for process management, memory allocation, and graceful shutdowns. Supervisor manages the Octane process, ensuring it starts with the container and handles restarts appropriately. The configuration includes proper user permissions, logging, and integration with the existing Nginx setup.

Debugging Laravel Applications with Xdebug

Xdebug is essential for debugging Laravel applications in Docker environments. It provides step-by-step debugging, profiling, and code coverage analysis, making it easier to identify and resolve issues during development.

XDEBUG_ENABLED=true
XDEBUG_MODE=develop,coverage,debug,profile
XDEBUG_HOST=host.docker.internal
XDEBUG_IDE_KEY=DOCKER
XDEBUG_LOG=/dev/stdout
XDEBUG_LOG_LEVEL=0

php-fpm:
  build:
    context: .
    dockerfile: ./docker/php-fpm/Dockerfile
    target: development
    args:
      XDEBUG_ENABLED: ${XDEBUG_ENABLED:-true}
      XDEBUG_MODE: develop,coverage,debug,profile
      XDEBUG_HOST: ${XDEBUG_HOST:-host.docker.internal}

Health Checks and Monitoring

Comprehensive health checks are essential for production Docker deployments. A well-designed health check script verifies that all critical services are running, the application is responding to requests, database connections are functional, and file permissions are correct. The health check should be lightweight, fast, and provide clear error messages for troubleshooting.

Docker's built-in health check feature integrates with orchestration platforms like Docker Swarm and Kubernetes, enabling automatic container replacement when health checks fail. The health check script should test multiple aspects of the application, including HTTP endpoints, database connectivity, and file system permissions.

Security Best Practices

Security in Laravel Docker deployments involves multiple layers of protection. Container security starts with using minimal base images, running processes as non-root users, and implementing proper file permissions. The application layer requires secure environment variable handling, proper secret management, and regular security updates.

Network security includes configuring proper firewall rules, using HTTPS in production, and implementing security headers. The Nginx configuration should include rate limiting, request size limits, and protection against common web vulnerabilities. Regular security audits and dependency updates are essential for maintaining a secure deployment.

Performance Optimization Strategies

Performance optimization in Laravel Docker containers involves multiple strategies working together. Image optimization includes using Alpine Linux base images, implementing multi-stage builds, and removing unnecessary packages. Runtime optimization involves proper PHP-FPM configuration, Opcache tuning, and efficient static file serving.

Database optimization includes connection pooling, query caching, and proper indexing. Application-level optimizations involve route caching, configuration caching, and view compilation. Monitoring and profiling tools help identify bottlenecks and measure the effectiveness of optimization efforts.

Docker Compose Configuration

Docker Compose is a powerful tool for managing multi-container environments, particularly in development due to its simplicity. With Docker Compose, you can define and connect all necessary services for Laravel, such as PHP, Nginx, and databases, in a single configuration file. This setup ensures consistency across development, testing, and production environments, streamlining onboarding and reducing discrepancies between local and server setups.

app:
  build:
    context: .
    dockerfile: Dockerfile
  image: your-laravel-app
  container_name: laravel-app
  ports:
    - "8000:8000"
  volumes:
    - .:/var/www/html
  networks:
    - app-network

nginx:
  image: nginx:alpine
  container_name: nginx-container
  ports:
    - "80:80"
  volumes:
    - ./nginx/conf.d:/etc/nginx/conf.d
    - ./public:/var/www/html/public
  depends_on:
    - app
  networks:
    - app-network

mysql:
  image: mysql:8.0
  container_name: mysql-container
  environment:
    MYSQL_ROOT_PASSWORD: root_password
    MYSQL_DATABASE: laravel_db
    MYSQL_USER: laravel_user
    MYSQL_PASSWORD: laravel_password
  volumes:
    - mysql_data:/var/lib/mysql
  networks:
    - app-network

Development vs Production Configurations

Understanding the differences between development and production Docker configurations is crucial for creating effective Laravel applications. Each environment has specific requirements and optimizations that must be carefully considered.

Deployment and CI/CD Integration

Modern deployment strategies for Laravel Docker applications involve continuous integration and continuous deployment pipelines. The Dockerfile should be optimized for build caching, with frequently changing files copied last to maximize cache utilization. Build arguments and multi-platform builds enable deployment across different architectures.

CI/CD pipelines should include automated testing, security scanning, and performance testing. Deployment strategies like blue-green deployments and rolling updates minimize downtime and reduce deployment risks. Environment-specific configurations ensure proper behavior across development, staging, and production environments.

Troubleshooting Common Issues

Common issues in Laravel Docker deployments include permission problems, memory limitations, and service startup failures. Permission issues often arise from file ownership conflicts between the host system and container. Proper user creation and file permission management prevent these problems.

php artisan cache:clear
php artisan route:clear
php artisan config:clear
php artisan view:clear

Memory issues can occur when containers exceed allocated resources or when applications have memory leaks. Proper resource limits, monitoring, and garbage collection tuning help prevent these problems. Service startup failures often result from configuration errors, missing dependencies, or network connectivity issues.

Monitoring and Logging

Effective monitoring and logging are crucial for maintaining healthy Laravel Docker deployments. Centralized logging enables tracking application behavior, identifying errors, and analyzing performance patterns. Log aggregation tools like ELK Stack or Fluentd collect logs from multiple containers and provide searchable interfaces.

Application Performance Monitoring (APM) tools provide insights into application behavior, database performance, and external service dependencies. Metrics collection includes system resources, application metrics, and business metrics. Alerting systems notify administrators of critical issues requiring immediate attention.

Scaling and Load Balancing

Scaling Laravel Docker applications involves horizontal scaling through multiple container instances and load balancing. Load balancers distribute incoming requests across multiple container instances, improving availability and performance. Session management and stateful application considerations are important for scaling decisions.

Database scaling strategies include read replicas, connection pooling, and caching layers. Queue scaling involves multiple worker processes and distributed queue systems. Auto-scaling based on metrics like CPU usage, memory consumption, and request rates ensures optimal resource utilization.

Frequently Asked Questions