zeacom/phpfpm-caddy repository overview

⁠Docker Image with s6-overlay, PHP-FPM, and Caddy

This repository provides a Docker image based on Debian Trixie that includes:

• s6-overlay⁠: A process supervisor for Docker containers.
• PHP-FPM⁠: FastCGI Process Manager for handling PHP scripts.
• Caddy⁠: A powerful, enterprise-ready, open-source web server with automatic HTTPS.

The image is designed to serve PHP applications efficiently using Caddy as the web server and PHP-FPM for processing.

An alternative Alpine-based image is also available via Dockerfile.alpine.

⁠Table of Contents

• Features⁠
• Getting Started⁠
  • Prerequisites⁠
  • Building the Image⁠
  • Running the Container⁠
• Important Commands⁠
  • Service Management⁠
  • Caddy Commands⁠
  • PHP-FPM Commands⁠
• Configuration Files⁠
• PHP Extensions⁠
• Entrypoint⁠
• Customization⁠
• CI/CD⁠
• Troubleshooting⁠
• Additional Resources⁠

⁠Features

• Debian Trixie (slim): Stable and well-supported base image.
• PHP 8.4 (default), with PHP 8.5 and PHP 8.3 available as build argument.
• s6-overlay 3.2.1.0: Process supervision and management.
• Caddy 2.10.2: Modern web server, installed directly from GitHub releases.
• Multi-architecture: Supports linux/amd64 and linux/arm64.
• Timezone Configuration: Set to Europe/Berlin by default.

⁠Getting Started

⁠Prerequisites

• Docker installed on your system (with buildx for multi-arch builds).
• Basic knowledge of Docker commands.

⁠Building the Image

Clone the repository:

git clone <repository-url>
cd <repository-directory>

Build with default settings (PHP 8.4):

docker build -t my-php-caddy-image .

⁠Specify build arguments to customize PHP, s6-overlay, or Caddy versions:

docker build \
  --build-arg ENV_PHP_VERSION=8.3 \
  --build-arg S6_OVERLAY_VERSION=3.2.1.0 \
  --build-arg CADDY_VERSION=2.10.2 \
  -t my-php-caddy-image .

⁠Multi-architecture build:

docker buildx build --platform linux/amd64,linux/arm64 \
  --build-arg ENV_PHP_VERSION=8.4 \
  -t my-php-caddy-image .

⁠Alpine variant

An alternative Alpine-based image (Dockerfile.alpine) is available with PHP 8.2 and s6-overlay 3.2.0.0:

docker build -f Dockerfile.alpine -t my-php-caddy-alpine .

⁠Important Commands

⁠Service Management

⁠Restart Caddy Service

/command/s6-svc -r /run/service/caddy

⁠Restart PHP-FPM Service

/command/s6-svc -r /run/service/php-fpm

⁠List all services and their statuses

s6-rc -a list

⁠Check the status of a specific service (e.g., Caddy)

s6-svstat /run/service/caddy

⁠Configuration Files

Configuration files are located in the config/ and php-fpm/ directories.

• Entrypoint Script: config/entrypoint.sh
• Caddy Configuration:
  • Main: config/etc/caddy/Caddyfile
  • Snippets: config/etc/caddy/snippets/
    • headers_default.caddy — Default response headers
    • headers_security.caddy — Security headers (HSTS, X-Frame-Options, etc.)
    • logging.caddy — Request logging
    • static_caching.caddy — Static asset caching (CSS, JS, fonts, images)
• PHP-FPM Configuration:
  • Main Config: php-fpm/php-fpm.conf
  • Pool Config: php-fpm/www.conf
  • Custom PHP Settings: php-fpm/php-vars.ini
• s6-overlay Services:
  • Service Definitions: config/etc/s6-overlay/s6-rc.d/

⁠s6-rc.d Directory Structure

The s6-rc.d directory contains service definitions for s6-overlay, organized to manage services like caddy and php-fpm.

• caddy and php-fpm Directories:

  • dependencies.d: Lists dependencies required by the service to start. caddy depends on php-fpm, php-fpm depends on base.
  • run: The main command to start the service as a longrun process.
  • finish: Cleanup commands that run when the service stops.
  • type: Set to longrun for automatic restart on failure.

• user Directory:

  • contents.d: Registers caddy and php-fpm as user services.

⁠PHP Extensions

The following PHP extensions are installed by default (Debian variant):

bcmath, bz2, calendar, cli, curl, gd, gmp, imagick, intl, mbstring, memcache, mysql, opcache, pgsql, redis, soap, sqlite3, xml, zip

⁠Entrypoint

The entrypoint script (config/entrypoint.sh) performs the following steps:

1. Loads .env.docker from /var/www/html/.env.docker if present.
2. Processes template substitutions via /docker/scripts/envsubst_mapping.sh if present.
3. Runs a bootstrap script from /docker/scripts/bootstrap.sh if present.
4. Falls back to /init (s6-overlay) if no arguments are provided.

⁠Customization

⁠Changing the Timezone

Modify the TIMEZONE environment variable in the Dockerfile:

ENV TIMEZONE=Your/Timezone

⁠Adding PHP Extensions

In the Dockerfile, update the apt install command:

php$PHP_VERSION-<extension-name>

⁠Modifying PHP Settings

Edit php-fpm/php-vars.ini to change PHP settings like memory_limit, upload_max_filesize, etc.

⁠Updating Caddy Configuration

Edit config/etc/caddy/Caddyfile and the snippets in config/etc/caddy/snippets/ to customize Caddy's behavior.

⁠CI/CD

The project includes a GitLab CI pipeline (.gitlab-ci.yml) that:

• Builds multi-architecture images (linux/amd64, linux/arm64) for PHP 8.5, PHP 8.4 and PHP 8.3 in parallel.
• Pushes to Docker Hub as zeacom/phpfpm-caddy:{tag}-php{version}.
• Updates the Docker Hub README automatically.
• Triggered on git tags only.

⁠Troubleshooting

⁠Service Fails to Start

Check the logs for the failing service:

s6-svlogd -tt /run/service/<service-name>/log

⁠Permission Issues

Ensure that file permissions are set correctly for the web server and PHP-FPM processes.

⁠Configuration Errors

Validate configurations:

• Caddy: caddy validate --config /etc/caddy/Caddyfile
• PHP-FPM: php-fpm -t

⁠Logs Location

• Caddy Logs: Check /var/log/caddy/ inside the container.
• PHP-FPM Logs: Check /var/log/php-fpm.log or the configured log file.

⁠Additional Resources

• s6-overlay Documentation⁠
• PHP-FPM Documentation⁠
• Caddy Documentation⁠