jkaninda/laravel-php-fpm repository overview

⁠🐳 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.

⁠

⁠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 Queue Worker started automatically (Supervisord).
• Custom Configuration: Pre-configured with sensible defaults, tunable through environment variables.
• Debian and Alpine variants, multi-arch (linux/amd64, linux/arm64).
• Production-ready: healthcheck, graceful shutdown, OPcache, supervisorctl support.
• Event Handling: Support for advanced event-driven processes.
• Optimized for Microservices: Built with modern PHP microservices in mind.

This image is ideal for developers looking for a streamlined, high-performance solution to deploy PHP applications with essential tools already integrated.

⁠Links:

• Docker Hub⁠
• Github⁠

⁠Supported PHP Versions & Tags

Legacy images (PHP is end-of-life, no longer rebuilt automatically or tested): 8.1, 8.1-alpine, 8.0, 7.4, 7.3, 7.2.

⁠Specifications

⁠PHP Extensions

• Composer 2
• OpenSSL
• XML
• PDO (MySQL, PostgreSQL and SQLite)
• Rdkafka
• Redis
• Mbstring
• Intl
• Exif
• PCNTL
• ZIP
• GD (FreeType, JPEG, PNG, WebP)
• BCMath
• Memcached
• Opcache

⁠Additional Features

• Laravel Scheduler
• Laravel Queue Worker
• Supervisord
• Node.js 24 LTS and NPM
• Git, Zip/Unzip, SQLite CLI

⁠Getting Started

⁠Simple Docker-Compose Example

services:
  php-fpm:
    image: jkaninda/laravel-php-fpm:latest
    container_name: php-fpm
    restart: unless-stopped
    user: www-data # For production
    volumes:
      - ./:/var/www/html
    networks:
      - default
  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:
      - default

⁠Basic Commands

• Start Containers

  docker compose up -d
  

  Copy

• Create a Laravel Project

  docker compose exec php-fpm composer create-project --prefer-dist laravel/laravel .
  

  Copy

• Generate Application Key

  docker compose exec php-fpm php artisan key:generate
  

  Copy

• Create Storage Symlink

  docker compose exec php-fpm php artisan storage:link
  

  Copy

• Fix Permissions

  docker compose exec -u root php-fpm chown -R www-data:www-data storage bootstrap/cache
  

  Copy

• Run Laravel Migrations

  docker compose exec php-fpm php artisan migrate
  

  Copy

• Access the Container Shell

  docker exec -it php-fpm bash
  

  Copy

• Run a one-off command (the default supervisor stack is not started)

  docker run --rm -v "$PWD:/var/www/html" jkaninda/laravel-php-fpm composer install
  

  Copy

• Restart the queue workers after a deployment

  docker compose exec php-fpm supervisorctl restart all
  

  Copy

⁠Environment Variables

⁠Laravel

The scheduler and queue worker are only started when an artisan file is found in APP_DIR.

⁠PHP

⁠OPcache

⁠PHP-FPM

Container environment variables (e.g. DB_HOST, APP_KEY) are passed to PHP-FPM workers (clear_env = no).

⁠Development example

services:
  php-fpm:
    image: jkaninda/laravel-php-fpm:8.5
    environment:
      PHP_OPCACHE_VALIDATE_TIMESTAMPS: 1
      PHP_DISPLAY_ERRORS: "On"
      LARAVEL_QUEUE_OPTIONS: "redis --sleep=3 --tries=3"
      LARAVEL_PROCS_NUMBER: 2
    volumes:
      - ./:/var/www/html

⁠Advanced Usage with Nginx

⁠Docker-Compose with Nginx

Example of using a custom nginx config:

services:
  php-fpm:
    image: jkaninda/laravel-php-fpm
    container_name: php-fpm
    restart: unless-stopped
    volumes:
      - ./:/var/www/html
    networks:
      - default

  nginx-server:
    image: nginx:alpine
    container_name: nginx-server
    restart: unless-stopped
    ports:
      - 80:80
    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

⁠Nginx Configuration (default.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;
}

⁠Custom Build

⁠Dockerfile Example

FROM jkaninda/laravel-php-fpm:8.5
# Copy Laravel project files
COPY . /var/www/html
VOLUME /var/www/html/storage
WORKDIR /var/www/html

# Fix permissions
RUN chown -R www-data:www-data /var/www/html

USER www-data

⁠Supervisord Integration

⁠Adding Custom Supervisor Processes

Place configurations in /etc/supervisor/conf.d/.
Example Kafka consumer process:

[program:kafkaconsume-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan kafka:consumer
autostart=true
autorestart=true
numprocs=1
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/html/storage/logs/kafka.log

⁠Custom PHP Configurations

Most common settings can be changed with environment variables⁠. For anything else, either:

• mount or copy your own .ini file into /usr/local/etc/php/conf.d/, or
• place a php.ini file at conf/php/php.ini in your project; it is copied into conf.d at startup.

⁠Storage Permissions Fix

www-data has UID/GID 1000 in both Debian and Alpine variants. If you encounter permission issues, run:

docker compose exec -u root php-fpm chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
docker compose exec -u root php-fpm chmod -R 775 /var/www/html/storage

To match your host user, rebuild with --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g).

⁠Building & Testing Locally

make build-8.5          # Debian image
make build-8.5-alpine   # Alpine image
make test               # Integration test (Laravel + MySQL + Nginx)

⁠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?

Check out my other project — 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!