joaopinto14/production repository overview

⁠Production

Production is a lightweight, production-focused Docker image for running PHP applications with Nginx + PHP-FPM.

It provides a small, secure, non-root runtime designed for containerized production workloads, with dedicated images for both generic PHP applications and Laravel.

⁠Source code & documentation

The complete source code, documentation, migration guides, tests, and release history are available on GitHub:

https://github.com/joaopinto14/Production⁠

Issues and contributions should also be submitted through the GitHub repository.

⁠Features

• Alpine Linux
• Nginx + PHP-FPM
• PHP 8.3, 8.4 and 8.5
• Generic PHP and Laravel variants
• linux/amd64
• linux/arm64
• Non-root runtime
• Built-in /healthz endpoint
• Docker health check
• stdout/stderr logging
• Graceful shutdown
• Runtime crash detection
• Read-only root filesystem compatible
• CLI workloads without starting Nginx/PHP-FPM
• No Supervisor
• No Python
• No Composer in the runtime image
• No Node.js in the runtime image
• No build tools in the runtime image

⁠Quick start

⁠Generic PHP

For a PHP application with an index.php in its root directory:

docker run --rm \
  -p 8080:8080 \
  -v "$PWD:/var/www/html:ro" \
  joaopinto14/production:2.0.0-php8.5

Open:

http://localhost:8080

The default document root for the Generic variant is:

/var/www/html

⁠Laravel

For a Laravel application with dependencies already installed:

docker run --rm \
  -p 8080:8080 \
  -v "$PWD:/var/www/html:ro" \
  -v "$PWD/storage:/var/www/html/storage" \
  -v "$PWD/bootstrap/cache:/var/www/html/bootstrap/cache" \
  joaopinto14/production:2.0.0-laravel-php8.5

The Laravel variant automatically uses:

/var/www/html/public

as the document root.

Laravel writable directories such as storage and bootstrap/cache must be writable by the container runtime user.

⁠Available images

⁠Generic PHP

The following aliases point to the Generic PHP 8.5 image:

joaopinto14/production:2.0.0
joaopinto14/production:latest

⁠Laravel

The following alias points to Laravel with PHP 8.5:

joaopinto14/production:laravel

For reproducible production deployments, versioned tags are recommended.

Example:

joaopinto14/production:2.0.0-laravel-php8.5

⁠Architecture

Production keeps the runtime architecture intentionally simple:

HTTP :8080
    │
    ▼
  Nginx
    │
    ▼
 PHP-FPM
    │
    ▼
PHP application

The container uses a lightweight built-in process manager:

production-runtime
├── Nginx
└── PHP-FPM

It is responsible for:

• starting Nginx and PHP-FPM;
• forwarding Unix signals;
• graceful shutdown;
• detecting unexpected Nginx or PHP-FPM termination;
• stopping the container when a managed process fails.

Production does not use Supervisor, systemd or Python.

⁠Laravel CLI workloads

The same Laravel image can be used for web requests and CLI workloads.

When a custom command is supplied, Production executes it directly instead of starting Nginx and PHP-FPM.

⁠Artisan

docker run --rm \
  -v "$PWD:/var/www/html" \
  joaopinto14/production:2.0.0-laravel-php8.5 \
  php artisan about

⁠Migrations

docker run --rm \
  -v "$PWD:/var/www/html" \
  joaopinto14/production:2.0.0-laravel-php8.5 \
  php artisan migrate --force

⁠Queue worker

docker run --rm \
  -v "$PWD:/var/www/html" \
  joaopinto14/production:2.0.0-laravel-php8.5 \
  php artisan queue:work

⁠Scheduler

docker run --rm \
  -v "$PWD:/var/www/html" \
  joaopinto14/production:2.0.0-laravel-php8.5 \
  php artisan schedule:work

This allows the exact same image to be reused for:

• web containers;
• queue workers;
• schedulers;
• migrations;
• maintenance commands;
• other PHP CLI workloads.

⁠Configuration

Production supports runtime configuration through environment variables.

Example:

docker run --rm \
  -p 8080:8080 \
  -e TIMEZONE=Europe/Lisbon \
  -e PHP_MEMORY_LIMIT=512M \
  -e UPLOAD_MAX_SIZE=100M \
  -v "$PWD:/var/www/html:ro" \
  joaopinto14/production:2.0.0-php8.5

⁠Docker Compose

⁠Generic PHP

services:
  app:
    image: joaopinto14/production:2.0.0-php8.5

    ports:
      - "8080:8080"

    environment:
      TIMEZONE: Europe/Lisbon
      PHP_MEMORY_LIMIT: 256M
      UPLOAD_MAX_SIZE: 50M

    volumes:
      - ./app:/var/www/html:ro

    restart: unless-stopped

⁠Laravel

services:
  app:
    image: joaopinto14/production:2.0.0-laravel-php8.5

    ports:
      - "8080:8080"

    environment:
      TIMEZONE: Europe/Lisbon
      PHP_MEMORY_LIMIT: 512M
      UPLOAD_MAX_SIZE: 100M

    volumes:
      - ./:/var/www/html:ro
      - ./storage:/var/www/html/storage
      - ./bootstrap/cache:/var/www/html/bootstrap/cache

    restart: unless-stopped

⁠Health check

Production provides:

/healthz

Example:

curl http://localhost:8080/healthz

The Docker images also contain a built-in health check.

⁠Logging

Nginx and PHP runtime logs are written to container stdout/stderr.

Use:

docker logs <container>

or:

docker logs -f <container>

No application log files need to be collected from inside the container for the web runtime.

⁠Security

Production 2.0 is designed to work with hardened container deployments.

The runtime:

• runs as a non-root user;
• does not require Supervisor;
• does not require Python;
• supports dropped Linux capabilities;
• supports no-new-privileges;
• supports a read-only root filesystem;
• uses explicit writable runtime directories;
• does not recursively chown application files when starting.

Example hardened deployment:

services:
  app:
    image: joaopinto14/production:2.0.0-laravel-php8.5

    read_only: true

    security_opt:
      - no-new-privileges:true

    cap_drop:
      - ALL

    tmpfs:
      - /run/production
      - /tmp

Application-specific writable paths such as Laravel's storage and bootstrap/cache must still be provided with appropriate permissions.

⁠Laravel PHP extensions

The Laravel variant includes commonly required extensions for modern Laravel applications, including support for:

• BCMath
• DOM
• Intl
• PCNTL
• PDO
• MySQL / MariaDB
• PostgreSQL
• SQLite
• Redis / PhpRedis
• ZIP

The Generic variant intentionally contains a smaller set of PHP extensions.

⁠What is not included

Production is a runtime image, not a development/build environment.

The runtime intentionally does not include tools such as:

Composer
Node.js
npm
Git
Python
Supervisor
build toolchains

Dependencies and application assets should be prepared during CI/CD or a multi-stage Docker build before the application is deployed.

⁠Multi-architecture

Production images are published for:

linux/amd64
linux/arm64

Docker automatically selects the appropriate architecture when pulling an image.

Example:

docker pull joaopinto14/production:2.0.0-php8.5

This allows the same image tag to be used on x86-64 servers and ARM64 systems.

⁠Migrating from Production 1.x

Production 2.0 contains several breaking changes compared with Production 1.1.3, including:

• internal HTTP port changed from 80 to 8080;
• runtime now runs as non-root;
• Supervisor and Python were removed;
• INDEX_PATH was replaced by DOCUMENT_ROOT;
• MEMORY_LIMIT was replaced by PHP_MEMORY_LIMIT;
• runtime PHP extension installation was removed;
• automatic recursive application ownership changes were removed;
• dedicated Laravel variants were introduced;
• multi-architecture images were introduced.

Before upgrading an existing deployment, read the complete migration guide:

https://github.com/joaopinto14/Production/blob/main/MIGRATION.md⁠

⁠Documentation

Full documentation is maintained in the GitHub repository:

Repository:
https://github.com/joaopinto14/Production⁠

README:
https://github.com/joaopinto14/Production/blob/main/README.md⁠

Migration guide:
https://github.com/joaopinto14/Production/blob/main/MIGRATION.md⁠

Changelog:
https://github.com/joaopinto14/Production/blob/main/CHANGELOG.md⁠

Release information:
https://github.com/joaopinto14/Production/blob/main/RELEASE.md⁠

⁠Issues and contributions

Bug reports, feature requests, and contributions are welcome through GitHub:

https://github.com/joaopinto14/Production/issues⁠

Source code:

https://github.com/joaopinto14/Production⁠

⁠Production 2.0.0

Production 2.0.0 provides a compact and hardened PHP runtime with:

Alpine Linux
+ Nginx
+ PHP-FPM
+ Production Runtime Manager

with dedicated Generic and Laravel images for PHP 8.3, 8.4 and 8.5 on AMD64 and ARM64.