jkaninda/nginx-php-fpm repository overview

⁠🐳 Docker Image: Nginx PHP-FPM

A ready-to-use container designed for running PHP-based applications, including Laravel microservices. This Docker image combines Nginx and 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.
• Nginx and PHP-FPM in one container, managed by Supervisord.
• 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.
• 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, logs on stdout, supervisorctl support.
• 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 Repository⁠

⁠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

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

⁠Basic Usage with Docker Compose

⁠Example docker-compose.yml

services:
  app:
    image: jkaninda/nginx-php-fpm:8.5
    container_name: app
    restart: unless-stopped
    volumes:
      # Project root
      - ./src:/var/www/html
    ports:
      - "80:80"

⁠Commands

⁠Start the service:

docker compose up -d

⁠Create a new Laravel project:

docker compose exec -u www-data app composer create-project --prefer-dist laravel/laravel .

⁠Generate application key:

docker compose exec -u www-data app php artisan key:generate

⁠Create a storage symlink:

docker compose exec -u www-data app php artisan storage:link

⁠Fix storage and cache permissions:

docker compose exec app chown -R www-data:www-data storage bootstrap/cache

⁠Run Laravel migrations:

docker compose exec -u www-data app php artisan migrate

⁠Access the container shell:

docker exec -it app bash

⁠Run a one-off command (Nginx and PHP-FPM are not started):

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

⁠Restart the queue workers after a deployment:

docker compose exec app supervisorctl restart Laravel-worker:*

⁠Environment Variables

⁠Nginx

⁠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:
  app:
    image: jkaninda/nginx-php-fpm:8.5
    ports:
      - "80:80"
    environment:
      PHP_OPCACHE_VALIDATE_TIMESTAMPS: 1
      PHP_DISPLAY_ERRORS: "On"
      CLIENT_MAX_BODY_SIZE: 20M
      LARAVEL_QUEUE_OPTIONS: "redis --sleep=3 --tries=3"
      LARAVEL_PROCS_NUMBER: 2
    volumes:
      - ./:/var/www/html

⁠Custom Build Example

⁠Dockerfile

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

WORKDIR /var/www/html

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

⁠Custom Nginx Configuration

To use custom Nginx configurations, add the following files to your project:

• conf/nginx/nginx.conf: replaces /etc/nginx/nginx.conf
• conf/nginx/nginx-site.conf: replaces the generated server block. PHP-FPM listens on 127.0.0.1:9000.

⁠Custom PHP Configuration

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.

⁠Supervisord Integration

Supervisord can be used to manage tasks or processes within the container.
Place your programs in conf/worker/supervisor.conf in your project, or mount them into /etc/supervisor/conf.d/.

⁠Example Configuration for Kafka Consumer

[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

⁠Fixing Storage Permissions

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

docker compose exec app chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
docker compose exec app 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)

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