PHP Docker Images

https://serversideup.net/open-source/docker-php/docs
Admin
A set of production-ready PHP Docker images that enhance official PHP images with better security,...
Tokens:86,533
Snippets:750
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### install-php-extensions - Install intl extension

Source: https://serversideup.net/open-source/docker-php/docs/reference/command-reference

Wrapper around docker-php-ext-install from official PHP Docker images. Allows installing PHP extensions with a single command. Example installs the 'intl' extension.

```bash
install-php-extensions intl

```

--------------------------------

### Install PHP extension installer

Source: https://serversideup.net/open-source/docker-php/docs/reference/command-reference

Installs the PHP extension installer using the internal helper script. The version is passed as an argument.

```bash
# Usage: docker-php-serversideup-install-php-ext-installer [version]
docker-php-serversideup-install-php-ext-installer 2.2.0

```

--------------------------------

### Install a single package on Alpine with docker-php-serversideup-dep-install-alpine

Source: https://serversideup.net/open-source/docker-php/docs/reference/command-reference

Installs the git package on an Alpine-based system. The command detects the OS and installs packages if Alpine. Must be run as root because the image is unprivileged by default.

```bash
# Usage: docker-php-serversideup-dep-install-alpine [alpine-packages]
docker-php-serversideup-dep-install-alpine git

```

--------------------------------

### Install multiple packages on Alpine with docker-php-serversideup-dep-install-alpine

Source: https://serversideup.net/open-source/docker-php/docs/reference/command-reference

Shows three ways to pass multiple packages: separate arguments, comma-separated list, and backslash continuations for Dockerfiles. All install the same packages on Alpine.

```bash
# Separate arguments
docker-php-serversideup-dep-install-alpine git zip unzip

# Comma-separated
docker-php-serversideup-dep-install-alpine "git, zip, unzip"

# Backslash continuations (useful in a Dockerfile)
docker-php-serversideup-dep-install-alpine \
    git \
    zip \
    unzip

```

--------------------------------

### Install a Debian package with docker-php-serversideup-dep-install-debian

Source: https://serversideup.net/open-source/docker-php/docs/reference/command-reference

Detects the operating system and installs the given package if it is Debian-based. Useful when building multiple OS variants from the same Dockerfile. The example installs the git package.

```bash
# Usage: docker-php-serversideup-dep-install-debian [debian-packages]
docker-php-serversideup-dep-install-debian git

```

--------------------------------

### Example image tag: serversideup/php:8.4-fpm-nginx

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/choosing-an-image

Shows the tag format for a specific PHP version and variation. This example uses PHP 8.4 with the fpm-nginx variation, and since no registry is specified, it defaults to Docker Hub.

```text
serversideup/php:8.4-fpm-nginx
```

--------------------------------

### Install PHP extensions with install-php-extensions

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/these-images-vs-others

Use this Dockerfile to install PHP extensions with the included install-php-extensions tool. It switches to root, installs bcmath, imagick, and mongodb, then returns to the unprivileged www-data user.

```dockerfile
FROM serversideup/php:8.5-cli

# Switch to root to install extensions
USER root

# Install any PHP extension easily
RUN install-php-extensions bcmath imagick mongodb

# Switch back to unprivileged user
USER www-data

```

--------------------------------

### Install PHP extensions with override

Source: https://serversideup.net/open-source/docker-php/docs/reference/command-reference

Installs PHP extensions using install-php-extensions. The second argument is optional and contains space-separated name=source pairs to override the source for specific extensions. In this example, redis is built from the develop branch of phpredis/phpredis.

```bash
# Usage: docker-php-serversideup-install-php-extensions [extensions] [overrides]
docker-php-serversideup-install-php-extensions "opcache redis zip" "redis=phpredis/phpredis@develop"

```

--------------------------------

### Check Docker and Compose versions

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/installation

Checks the installed Docker and Docker Compose versions. If version numbers are displayed after running these commands, the setup is ready to continue.

```bash
docker --version

```

```bash
docker compose version

```

--------------------------------

### Install Octane and configure Swoole server

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Run these artisan commands to install Octane and set up the Swoole server. Use 'openswoole' instead of 'swoole' for Open Swoole.

```Terminal
docker compose run php composer require laravel/octane
docker compose run php php artisan octane:install --server=swoole

```

--------------------------------

### Dockerfile: Install intl and bcmath extensions

Source: https://serversideup.net/open-source/docker-php/docs/customizing-the-image/installing-additional-php-extensions

Use this Dockerfile to install PHP extensions in a serversideup/php image. Switch to root, run install-php-extensions, then switch back to the unprivileged www-data user.

```dockerfile
# Choose our base image
FROM serversideup/php:8.5-fpm-nginx

# Switch to root so we can do root things
USER root

# Install the intl and bcmath extensions with root permissions
RUN install-php-extensions intl bcmath

# Drop back to our unprivileged user
USER www-data

```

--------------------------------

### Run a test web server with Docker

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/contributing

Starts a temporary container from the serversideup/php:8.4-fpm-nginx image, mounting the current directory to /var/www/html and exposing ports 80 and 443. Useful for quickly verifying changes locally.

```bash
docker run --rm -v $(pwd):/var/www/html -p 80:8080 -p 443:8443 serversideup/php:8.4-fpm-nginx

```

--------------------------------

### Install Swoole extension in Dockerfile

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Use this Dockerfile to install the Swoole extension via install-php-extensions. Run as root, then switch back to www-data. For Open Swoole, replace 'swoole' with 'openswoole'.

```Dockerfile
FROM serversideup/php:8.5-cli

USER root
RUN install-php-extensions swoole
USER www-data

```

--------------------------------

### Docker Compose volume-based WordPress setup

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/wordpress/using-wordpress-with-docker

Example compose.yml file that mounts the current directory to /var/www/html in a WordPress container using the serversideup/php:8.5-fpm-apache image. This setup allows WordPress admin to update core, plugins, and themes normally.

```yaml
services:
  wordpress:
    image: serversideup/php:8.5-fpm-apache
    volumes:
      - ./:/var/www/html
    ports:
      - 80:8080
      - 443:8443

```

--------------------------------

### Docker Compose: WordPress with MariaDB

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm-apache

Example for hosting WordPress with the FPM-Apache image, including a MariaDB service. Sets SSL_MODE, PHP_MEMORY_LIMIT, and PHP_OPCACHE_ENABLE.

```yaml
services:
  wordpress:
    image: serversideup/php:8.5-fpm-apache
    ports:
      - "80:8080"
      - "443:8443"
    volumes:
      - ./wordpress:/var/www/html
    environment:
      SSL_MODE: "full"
      PHP_MEMORY_LIMIT: "512M"
      PHP_OPCACHE_ENABLE: "1"
    depends_on:
      - mariadb

  mariadb:
    image: mariadb:11
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:
```

--------------------------------

### Docker Compose: Basic FPM-Apache setup

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm-apache

Recommended for local development and production. Maps ports 80/443 to 8080/8443 and mounts ./ to /var/www/html. Enables opcache and full SSL mode.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-apache
    ports:
      - "80:8080"
      - "443:8443"
    volumes:
      - ./:/var/www/html
    environment:
      PHP_OPCACHE_ENABLE: "1"
      SSL_MODE: "full"
```

--------------------------------

### Example custom NGINX configuration

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm-nginx

Example custom NGINX server configuration adding custom headers, a location block for /api, and rate limiting.

```nginx
# Add custom headers
add_header X-Custom-Header "My Value" always;

# Custom location block
location /api {
    try_files $uri $uri/ /index.php?$query_string;
    
    # Additional settings for API endpoints
    client_max_body_size 50M;
}

# Rate limiting
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
location /api/ {
    limit_req zone=api burst=20 nodelay;
}

```

--------------------------------

### Dockerfile for S6 Overlay conversion (Dockerfile)

Source: https://serversideup.net/open-source/docker-php/docs/customizing-the-image/adding-your-own-start-up-scripts

Dockerfile example that converts entrypoint scripts to S6 Overlay services using docker-php-serversideup-s6-init. Copies custom entrypoint scripts and long-running services, adds the service to the user bundle, and switches back to the non-root user.

```dockerfile
FROM serversideup/php:8.5-fpm-nginx

# Set the user to root for our build steps
USER root

# If you have your own one-shot scripts, copy them to the entrypoint.d directory
COPY --chmod=755 ./entrypoint.d/ /etc/entrypoint.d/

# Convert every entrypoint script into an S6 Overlay service
RUN docker-php-serversideup-s6-init

# If you have your own long running services, copy them to the s6 directory
COPY --chmod=755 ./my-s6-service/ /etc/s6-overlay/s6-rc.d/my-s6-service/

# Add your service to the "user" bundle so S6 Overlay starts it with the container
RUN touch /etc/s6-overlay/user-bundles.d/user/contents.d/my-s6-service

# Drop back to the non-root user
USER www-data

```

--------------------------------

### Run production compose

Source: https://serversideup.net/open-source/docker-php/docs/deployment-and-production/packaging-your-app-for-deployment

Command to start the production compose stack for local testing.

```bash
docker compose -f compose.prod.yml up

```

--------------------------------

### Docker Compose: Basic FPM-NGINX setup

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm-nginx

Recommended approach for local development and production. Maps the current directory to /var/www/html, but the default document root is /var/www/html/public. Enables OPCache via PHP_OPCACHE_ENABLE.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - "80:8080"
    volumes:
      - ./:/var/www/html
    environment:
      PHP_OPCACHE_ENABLE: "1"
```

--------------------------------

### Production Dockerfile with dependencies

Source: https://serversideup.net/open-source/docker-php/docs/deployment-and-production/packaging-your-app-for-deployment

Production Dockerfile that installs PHP extensions and copies application files. It switches to root for installation, then back to www-data for security.

```dockerfile
FROM serversideup/php:8.5-fpm-nginx

# Switch to root to install dependencies and copy files
USER root

# Install PHP dependencies
RUN install-php-extensions intl bcmath

# Switch back to non-root user for security
USER www-data

# Copy application files with correct ownership
COPY --chown=www-data:www-data . /var/www/html

```

--------------------------------

### Volume mount example in compose.yml

Source: https://serversideup.net/open-source/docker-php/docs/guide/configuring-trusted-proxies

Shows how to mount a custom trusted proxy configuration file at runtime instead of baking it into the image. Replace the COPY instruction with this volume mount in your compose.yml.

```yaml
volumes:
  # Mount syntax: ./local/path:/container/path:ro
  - ./docker/trusted-proxy/aws-alb.conf:/etc/nginx/trusted-proxy/aws-alb.conf:ro

```

--------------------------------

### Install Chokidar for --watch flag

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Run this npm command to install Chokidar as a dev dependency, required for the --watch flag when not using FrankenPHP.

```bash
npm install --save-dev chokidar

```

--------------------------------

### Install multiple Debian packages with docker-php-serversideup-dep-install-debian

Source: https://serversideup.net/open-source/docker-php/docs/reference/command-reference

Shows three ways to pass multiple packages: separate arguments, comma-separated list, or backslash continuations (useful in a Dockerfile).

```bash
# Separate arguments
docker-php-serversideup-dep-install-debian git zip unzip

# Comma-separated
docker-php-serversideup-dep-install-debian "git, zip, unzip"

# Backslash continuations (useful in a Dockerfile)
docker-php-serversideup-dep-install-debian \
    git \
    zip \
    unzip

```

--------------------------------

### Install Laravel Octane with FrankenPHP

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Commands to install Laravel Octane and configure it to use the FrankenPHP server.

```bash
docker compose run php composer require laravel/octane
docker compose run php php artisan octane:install --server=frankenphp

```

--------------------------------

### Dockerfile: Install packages on frozen Bullseye image

Source: https://serversideup.net/open-source/docker-php/docs/guide/major-version-migrations

Use this Dockerfile to make apt-get install work again on frozen 7.4/8.0 or -bullseye tags. It rewrites /etc/apt/sources.list to archive.debian.org and snapshot.debian.org, disables the apt expiry check, and updates install-php-extensions before installing intl. Note that this does not provide patched packages, only allows adding dependencies while migrating.

```dockerfile
FROM serversideup/php:7.4-fpm-nginx

USER root

RUN printf '%s\n' \
      'deb http://archive.debian.org/debian bullseye main' \
      'deb http://archive.debian.org/debian bullseye-updates main' \
      'deb http://snapshot.debian.org/archive/debian-security/20260903T220410Z bullseye-security main' \
      > /etc/apt/sources.list \
    && printf 'Acquire::Check-Valid-Until "false";\n' > /etc/apt/apt.conf.d/99no-check-valid-until \
    && docker-php-serversideup-install-php-ext-installer 2.11.15

RUN docker-php-serversideup-dep-install-debian "mariadb-client" \
    && install-php-extensions intl

USER www-data

```

--------------------------------

### Docker CLI: Run FPM-NGINX container

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm-nginx

Starts the serversideup/php:8.5-fpm-nginx container, mapping port 80 to 8080 and mounting the current directory to /var/www/html/public. The application will be available at http://localhost.

```bash
docker run -p 80:8080 -v $(pwd):/var/www/html/public serversideup/php:8.5-fpm-nginx
```

--------------------------------

### Run interactive bash with Docker Compose

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/cli

Starts a container using the compose configuration and opens an interactive bash shell.

```bash
docker compose run -it php bash

```

--------------------------------

### Create S6 Overlay user bundle file

Source: https://serversideup.net/open-source/docker-php/docs/guide/major-version-migrations

If your Dockerfile creates `/etc/s6-overlay/s6-rc.d/user/contents.d/<service>` to start your own service, you must create the empty file in the new `user-bundles.d/` directory instead. Do not recreate the old directory, as it will cause the container to fail to boot.

```Dockerfile
RUN touch /etc/s6-overlay/user-bundles.d/user/contents.d/my-service

```

--------------------------------

### Terminal: Install Octane and RoadRunner HTTP packages

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Composer command to install laravel/octane and spiral/roadrunner-http. This is required for RoadRunner support.

```Terminal
docker compose run php composer require laravel/octane spiral/roadrunner-http

```

--------------------------------

### Run Locally with Docker Compose

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Command to start the application locally with Octane running in worker mode.

```bash
docker compose up

```

--------------------------------

### Dockerfile: Install RoadRunner binary and sockets extension

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Base Dockerfile for running Octane with RoadRunner. Adds the sockets extension and downloads the RoadRunner binary using BuildKit's TARGETARCH. The binary is installed to /usr/local/bin/rr and the user is set back to www-data.

```Dockerfile
FROM serversideup/php:8.5-cli

USER root
RUN install-php-extensions sockets

# Install the RoadRunner binary. TARGETARCH is provided by BuildKit,
# so this works on both amd64 and arm64.
ARG TARGETARCH
ARG ROADRUNNER_VERSION=2025.1.15
RUN docker-php-serversideup-download \
      "https://github.com/roadrunner-server/roadrunner/releases/download/v${ROADRUNNER_VERSION}/roadrunner-${ROADRUNNER_VERSION}-linux-${TARGETARCH}.tar.gz" \
      /tmp/roadrunner.tar.gz && \
    tar -xzf /tmp/roadrunner.tar.gz -C /tmp && \
    mv "/tmp/roadrunner-${ROADRUNNER_VERSION}-linux-${TARGETARCH}/rr" /usr/local/bin/rr && \
    chmod +x /usr/local/bin/rr && \
    rm -rf /tmp/roadrunner*

USER www-data

```

--------------------------------

### Development compose.yml with mounted volume

Source: https://serversideup.net/open-source/docker-php/docs/deployment-and-production/packaging-your-app-for-deployment

Development configuration that mounts the application code as a volume for instant changes. This is the starting point before transitioning to production.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - 80:8080
    volumes:
      - ./:/var/www/html  # Your code mounted as a volume

```

--------------------------------

### Start Octane with Swoole in compose.yml

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Configure your compose service to run Octane with Swoole. The --host=0.0.0.0 flag is required for external access, and port 8000 is above 1024 so the unprivileged user can bind it.

```compose.yml
services:
  php:
    build:
      context: .
    ports:
      - "80:8000"
    volumes:
      - .:/var/www/html/
    # --host=0.0.0.0 is required so the port is reachable outside the container
    command: ["php", "artisan", "octane:start", "--server=swoole", "--host=0.0.0.0", "--port=8000"]
    healthcheck:
      test: ["CMD", "healthcheck-octane"]
      start_period: 10s

```

--------------------------------

### Enable OPcache preloading with PHP_OPCACHE_PRELOAD

Source: https://serversideup.net/open-source/docker-php/docs/guide/production-performance-tuning

Configure OPcache preloading by setting PHP_OPCACHE_PRELOAD to a preload script. The file must exist or PHP will refuse to start. Set this on the running service rather than as an ENV in the Dockerfile to avoid build steps depending on it.

```yaml
services:
  php:
    image: my-app:latest
    environment:
      PHP_OPCACHE_ENABLE: "1"
      PHP_OPCACHE_PRELOAD: "/var/www/html/config/preload.php"

```

--------------------------------

### Run CLI container with Docker CLI

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/cli

Mounts the current directory as /var/www/html and opens a bash shell inside the container where PHP is installed. Exit by typing 'exit'.

```bash
docker run -it -v $(pwd):/var/www/html serversideup/php:cli bash

```

--------------------------------

### Docker Compose: Laravel with MariaDB and Redis

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm-nginx

Full example for Laravel applications using the FPM-NGINX image. Includes SSL_MODE full, OPCache, and depends_on for MariaDB and Redis services. Uses named volumes for database and Redis data.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - "80:8080"
      - "443:8443"
    volumes:
      - .:/var/www/html
    environment:
      SSL_MODE: "full"
      PHP_OPCACHE_ENABLE: "1"
    depends_on:
      - mariadb
      - redis

  mariadb:
    image: mariadb:11
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: laravel
      MYSQL_USER: laravel
      MYSQL_PASSWORD: laravel
    volumes:
      - db_data:/var/lib/mysql

  redis:
    image: redis:alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data

volumes:
  db_data:
  redis_data:
```

--------------------------------

### Use custom SSL certificates (compose.yml)

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm-nginx

Mounts custom SSL certificate and key files into the container and sets SSL_MODE to 'full' for production-like setups. The certificate and key are mounted read-only.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - "443:8443"
    volumes:
      - ./:/var/www/html
      - ./certs/server.crt:/etc/ssl/private/self-signed-web.crt:ro
      - ./certs/server.key:/etc/ssl/private/self-signed-web.key:ro
    environment:
      SSL_MODE: "full"

```

--------------------------------

### Production low memory environment compose.yml

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm-nginx

Example docker-compose service configuration for production with low memory, enabling OPcache and adjusting NGINX FastCGI buffers.

```yaml
services:
  php:
    # You'll likely replace this with your own custom image name
    image: serversideup/php:8.5-fpm-nginx
    environment:
      # Enable OPcache for production
      PHP_OPCACHE_ENABLE: "1"
      
      # NGINX Settings (adjust as needed)
      NGINX_FASTCGI_BUFFERS: "16 16k"
      NGINX_FASTCGI_BUFFER_SIZE: "32k"

```

--------------------------------

### Dockerfile: Switch to root for build tasks

Source: https://serversideup.net/open-source/docker-php/docs/troubleshooting/common-issues

Use this Dockerfile when your build command fails due to permission issues. It switches to root to install system packages, then switches back to the non-root user www-data. Always switch back to a non-root user after privileged operations.

```dockerfile
FROM serversideup/php:8.5-fpm-nginx

USER root

# Install system packages
RUN install-php-extensions intl bcmath

# Switch back to www-data
USER www-data

```

--------------------------------

### Dockerfile for FPM-Apache custom trusted proxy

Source: https://serversideup.net/open-source/docker-php/docs/guide/configuring-trusted-proxies

Dockerfile example for the fpm-apache variant. Copies a custom trusted proxy configuration file into the image at /etc/apache2/trusted-proxy/aws-alb.conf.

```dockerfile
FROM serversideup/php:8.5-fpm-apache

# Copy our custom trusted proxy configuration
COPY --chmod=644 docker/trusted-proxy/aws-alb.conf /etc/apache2/trusted-proxy/aws-alb.conf

```

--------------------------------

### compose.yml: Update image and ports for serversideup/php

Source: https://serversideup.net/open-source/docker-php/docs/guide/migrating-from-official-php-images

Update your compose.yml file to use the serversideup/php image and adjust the port mappings accordingly. The example shows the original and updated service definitions.

```yaml
services:
  php:
    image: php:8.5-apache
    ports:
      - 80:80
      - 443:443

```

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-apache
    ports:
      - 80:8080
      - 443:8443

```

--------------------------------

### Dockerfile for FrankenPHP custom trusted proxy

Source: https://serversideup.net/open-source/docker-php/docs/guide/configuring-trusted-proxies

Dockerfile example for the frankenphp variant. Copies a custom trusted proxy configuration file into the image at /etc/frankenphp/trusted-proxy/aws-alb.caddyfile.

```dockerfile
FROM serversideup/php:8.5-frankenphp

# Copy our custom trusted proxy configuration
COPY --chmod=644 docker/trusted-proxy/aws-alb.caddyfile /etc/frankenphp/trusted-proxy/aws-alb.caddyfile

```

--------------------------------

### Dockerfile: Change base image from php:8.5-apache to serversideup/php:8.5-fpm-apache

Source: https://serversideup.net/open-source/docker-php/docs/guide/migrating-from-official-php-images

Replace the official PHP image with the serversideup/php image in your Dockerfile. The example shows the original and updated Dockerfile lines.

```dockerfile
FROM php:8.5-apache

# Rest of your Dockerfile...

```

```dockerfile
FROM serversideup/php:8.5-fpm-apache

# Rest of your Dockerfile...

```

--------------------------------

### Dockerfile for FPM-NGINX custom trusted proxy

Source: https://serversideup.net/open-source/docker-php/docs/guide/configuring-trusted-proxies

Dockerfile example for the fpm-nginx variant. Copies a custom trusted proxy configuration file into the image at /etc/nginx/trusted-proxy/aws-alb.conf.

```dockerfile
FROM serversideup/php:8.5-fpm-nginx

# Copy our custom trusted proxy configuration
COPY --chmod=644 docker/trusted-proxy/aws-alb.conf /etc/nginx/trusted-proxy/aws-alb.conf

```

--------------------------------

### Dockerfile: Copy custom entrypoint scripts

Source: https://serversideup.net/open-source/docker-php/docs/customizing-the-image/adding-your-own-start-up-scripts

Use this Dockerfile to copy your custom entrypoint scripts into the container's /etc/entrypoint.d/ directory. The --chmod=755 flag ensures the scripts are executable. This example copies the entire entrypoint.d directory.

```dockerfile
FROM serversideup/php:8.5-fpm-nginx

# Copy our scripts as executable
COPY --chmod=755 ./entrypoint.d/ /etc/entrypoint.d/

```

--------------------------------

### Enable Laravel Automations in compose.yml

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/these-images-vs-others

Use this compose.yml to run the serversideup/php:8.5-fpm-nginx image with Laravel Automations enabled via the AUTORUN_ENABLED environment variable. This triggers migrations, storage linking, caching, and other automated setup steps.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    environment:
      # Run migrations, storage link, caching, and more
      AUTORUN_ENABLED: "true"

```

--------------------------------

### Docker Compose with Separate NGINX: PHP-FPM and Nginx Config

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm

Sets up a two-container setup: one runs PHP-FPM from the serversideup/php:8.5-fpm image, the other runs NGINX. The NGINX config forwards PHP requests to the PHP container on port 9000 via fastcgi_pass php:9000, using Docker service names for networking. Requires both files to be created together in the same directory with compose.yml.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm
    volumes:
      - ./:/var/www/html

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./:/var/www/html
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - php

```

```nginx
server {
    listen 80;
    server_name localhost;
    root /var/www/html/public;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass php:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

--------------------------------

### Configure Laravel Reverb health check in compose.yml

Source: https://serversideup.net/open-source/docker-php/docs/guide/using-healthchecks-with-laravel

Add this healthcheck configuration to your compose.yml to use the healthcheck-reverb command, which checks if the reverb:start process is running.

```yaml
## Rest of your service configuration...
healthcheck:
  test: ["CMD", "healthcheck-reverb"]

```

--------------------------------

### Run a PHP script directly with Docker Compose

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/cli

Passes a command directly to the container without starting a shell. The first 'php' is the service name, the second is the command to run inside the container.

```bash
docker compose run php php my-script.php

```

--------------------------------

### compose.yml: Use different port

Source: https://serversideup.net/open-source/docker-php/docs/troubleshooting/common-issues

Example compose.yml configuration to use a different port (8080 and 8443) instead of the default port 80. Access your application at http://localhost:8080.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - "8080:8080"  # Use port 8080 instead
      - "8443:8443"

```

--------------------------------

### Download a file with docker-php-serversideup-download

Source: https://serversideup.net/open-source/docker-php/docs/reference/command-reference

Downloads a file with retries (five times with short backoff) and fails the build if the file never arrives. Useful in Dockerfiles to handle transient 500 errors from hosts like GitHub. The example shows downloading to a specific output file and piping to stdout.

```bash
# Usage: docker-php-serversideup-download <url> [output-file]
docker-php-serversideup-download https://example.com/tool.tar.gz /tmp/tool.tar.gz

# Without an output file, the download is written to stdout
docker-php-serversideup-download https://example.com/key.asc | gpg --dearmor > /usr/share/keyrings/example.gpg

```

--------------------------------

### Pin Docker image to v2.2.1 tag

Source: https://serversideup.net/open-source/docker-php/docs/guide/major-version-migrations

In version 3, the image tags changed. To stay on the v2 image, add '-v2.2.1' to the image tag. This example shows the image before and after the change.

```yaml
services:
  php:
    image: serversideup/php:8.2-fpm-nginx
    ports:
      - 80:80
    volumes:
      - .:/var/www/html

```

```yaml
services:
  php:
    image: serversideup/php:8.2-fpm-nginx-v2.2.1
    ports:
      - 80:80
    volumes:
      - .:/var/www/html

```

--------------------------------

### Update compose.yml for PHP 8.4 with FrankenPHP

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/installation

Example compose.yml configuration that uses PHP 8.4 with FrankenPHP, sets port 80 to 8080, mounts the current directory to /var/www/html, and sets environment variables to increase the upload limit to 500M and enable OPCache.

```yaml
services:
  php:
    # Change image to 8.4 with FrankenPHP
    image: serversideup/php:8.4-frankenphp
    ports:
      - 80:8080
    volumes:
      - ./:/var/www/html
    environment:
      # Increase the upload limit to 500M
      PHP_UPLOAD_MAX_FILE_SIZE: "500M"
      # Turn OPCache on
      PHP_OPCACHE_ENABLE: "1"

```

--------------------------------

### Docker Compose configuration for Horizon with Redis

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/horizon

Defines services for the Laravel app, Redis, and Horizon. Horizon uses the same image as the web service and runs the Artisan horizon command. Redis is configured with a password and appendonly mode. The stop_signal is set to SIGTERM for graceful shutdown, and a health check is included with a start period of 10 seconds.

```yaml
services:
  php:
    image: my/laravel-app

  redis:
    image: redis:6
    command: "redis-server --appendonly yes --requirepass redispassword"

  horizon:
    image: my/laravel-app
    command: ["php", "/var/www/html/artisan", "horizon"]
    stop_signal: SIGTERM
    healthcheck:
      test: ["CMD", "healthcheck-horizon"]
      start_period: 10s

```

--------------------------------

### Docker Compose for FrankenPHP with Automatic HTTPS

Source: https://serversideup.net/open-source/docker-php/docs/deployment-and-production/configuring-ssl

Example compose.yml that directly exposes FrankenPHP to the internet with automatic HTTPS via Let's Encrypt. It maps ports 80:8080 and 443:8443, sets the required environment variables, and mounts the current directory and persistent volumes for Caddy config and data.

```yaml
services:
  php:
    image: serversideup/php:8.5-frankenphp
    ports:
      - 80:8080
      - 443:8443
    environment:
      CADDY_AUTO_HTTPS: "on"
      CADDY_HTTPS_SERVER_ADDRESS: "https://example.com"
      SSL_MODE: "full"
    # Mount the current directory to /var/www/html
    volumes:
      - .:/var/www/html
      - config:/config
      - data:/data

  volumes:
    config:
    data:

```

--------------------------------

### Common Docker Compose Commands

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/container-basics

Essential Docker Compose commands for managing containers: start, stop, view logs, execute commands, rebuild, and remove images. The -f flag in 'docker compose logs -f' follows logs in real-time; press Ctrl+C to stop following.

```bash
# Start containers (creates if they don't exist)
docker compose up

# Start in background (detached mode)
docker compose up -d

# Stop and remove containers
docker compose down

# View running containers
docker compose ps

# View container logs
docker compose logs

# Follow logs in real-time
docker compose logs -f

# Execute a command in a running container
docker compose exec php php -v

# Rebuild containers after image changes
docker compose up --build

# Remove images to force fresh download
docker compose down --rmi all

```

--------------------------------

### Enable JIT with PHP_OPCACHE_JIT and PHP_OPCACHE_JIT_BUFFER_SIZE

Source: https://serversideup.net/open-source/docker-php/docs/guide/production-performance-tuning

Enable the JIT compiler by setting PHP_OPCACHE_JIT to 'tracing' and PHP_OPCACHE_JIT_BUFFER_SIZE to '64M'. The buffer is added on top of PHP_OPCACHE_MEMORY_CONSUMPTION, so 64M with the default makes a 320 MB segment. Measure response times before and after; if they do not move, leave it off.

```yaml
services:
  php:
    image: my-app:latest
    environment:
      PHP_OPCACHE_ENABLE: "1"
      PHP_OPCACHE_JIT: "tracing"
      PHP_OPCACHE_JIT_BUFFER_SIZE: "64M"

```

--------------------------------

### Docker Compose configuration for Laravel queue worker

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/queue

Defines a dedicated queue service using the same image as the web service. The command runs Artisan queue:work with --tries=3, sets SIGTERM as the stop signal for graceful shutdown, and includes a health check using the native healthcheck-queue script with a 10-second start period.

```yaml
services:
  php:
    image: my/laravel-app

  queue:
    image: my/laravel-app
    command: ["php", "/var/www/html/artisan", "queue:work", "--tries=3"]
    stop_signal: SIGTERM
    healthcheck:
      # This is our native healthcheck script for the queue
      test: ["CMD", "healthcheck-queue"]
      start_period: 10s

```

--------------------------------

### Create project structure

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/installation

Creates a project directory structure with a public subdirectory and then changes into the project directory.

```bash
mkdir -p my-php-project/public

```

```bash
cd my-php-project

```

--------------------------------

### Add a new site block (docs-proxy.caddyfile)

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/frankenphp

Creates a new site block for docs.example.com that reverse proxies to a service named docs on port 3000. Uses the CADDY_HTTP_PORT environment variable with a default of 8080. This file goes in caddyfile.d/ and cannot use request matchers defined globally.

```caddyfile
http://docs.example.com:{$CADDY_HTTP_PORT:8080} {
    reverse_proxy docs:3000
}

```

--------------------------------

### Build a FPM-NGINX image with PHP 8.2.12 on Debian Bookworm

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/contributing

Run this command to build a local Docker image with the specified variation, PHP version, and OS. The resulting image is tagged as serversideup/php:8.2.12-fpm-nginx-bookworm for testing and inspection.

```bash
bash scripts/dev.sh --variation fpm-nginx --version 8.2.12 --os bookworm

```

--------------------------------

### Worker Mode compose.yml

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

Updated Docker Compose configuration to start Octane in worker mode with the production-ready Caddyfile.

```yaml
services:
  php:
    image: serversideup/php:8.5-frankenphp
    ports:
      - "80:8080"
    volumes:
      - .:/var/www/html/
    # Start Octane in worker mode with our production-ready Caddyfile
    command: ["php", "artisan", "octane:start", "--server=frankenphp", "--port=8080", "--caddyfile=/etc/frankenphp/Caddyfile"]

```

--------------------------------

### Run a command in a service named app

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/container-basics

Shows the equivalent command when the service is named 'app' instead of 'php'. Replace the service name in the command accordingly.

```bash
docker compose run app php -v

```

--------------------------------

### compose.yml: Configure serversideup/php with environment variables

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/these-images-vs-others

Use this compose.yml to run the serversideup/php:8.5-fpm-nginx image with environment variables for PHP settings and autorun features. Set PHP_MEMORY_LIMIT, PHP_UPLOAD_MAX_FILE_SIZE, PHP_MAX_EXECUTION_TIME, PHP_OPCACHE_ENABLE, and AUTORUN_ENABLED to customize without modifying Dockerfiles or mounting config files.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    environment:
      # Change any PHP setting with environment variables
      PHP_MEMORY_LIMIT: "512M"
      PHP_UPLOAD_MAX_FILE_SIZE: "100M"
      PHP_MAX_EXECUTION_TIME: "180"
      PHP_OPCACHE_ENABLE: "1"
      
      # Run Migrations, Storage Link, Caching, and more
      AUTORUN_ENABLED: "true"
```

--------------------------------

### public/frankenphp-worker.php

Source: https://serversideup.net/open-source/docker-php/docs/framework-guides/laravel/octane

The worker script generated by octane:install that FrankenPHP keeps in memory. It sets base and public paths and requires the Octane worker.

```php
<?php

// Set a default for the application base path and public path if they are missing...
$_SERVER['APP_BASE_PATH'] = $_ENV['APP_BASE_PATH'] ?? $_SERVER['APP_BASE_PATH'] ?? __DIR__.'/..';
$_SERVER['APP_PUBLIC_PATH'] = $_ENV['APP_PUBLIC_PATH'] ?? $_SERVER['APP_PUBLIC_PATH'] ?? __DIR__;

require __DIR__.'/../vendor/laravel/octane/bin/frankenphp-worker.php';

```

--------------------------------

### Low-Memory Tuning with serversideup/php:8.5-fpm

Source: https://serversideup.net/open-source/docker-php/docs/image-variations/fpm

Configure the FPM container for low-memory environments. Uses ondemand PM with 10 children and an idle timeout of 10 seconds.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm
    environment:
      PHP_FPM_PM_CONTROL: "ondemand"
      PHP_FPM_PM_MAX_CHILDREN: "10"
      PHP_FPM_PM_PROCESS_IDLE_TIMEOUT: "10s"

```

--------------------------------

### Dockerfile: Multi-stage build to set UID/GID for development and preserve defaults for production

Source: https://serversideup.net/open-source/docker-php/docs/guide/understanding-file-permissions

This Dockerfile uses a multi-stage build to create a development image that changes the UID/GID of www-data to match the host machine, and a production image that preserves the default UID/GID (33:33). It runs docker-php-serversideup-set-id and docker-php-serversideup-set-file-permissions as root, then drops back to www-data. The production stage copies files with --chown=www-data:www-data.

```dockerfile
############################################
# Base Image
############################################
FROM serversideup/php:8.5-fpm-nginx-bookworm AS base

############################################
# Development Image
############################################
FROM base AS development

# Switch to root so we can do root things
USER root

# Save the build arguments as a variable
ARG USER_ID
ARG GROUP_ID

# Use the build arguments to change the UID 
# and GID of www-data while also changing 
# the file permissions for NGINX
RUN docker-php-serversideup-set-id www-data $USER_ID:$GROUP_ID && \
    \
    # Update the file permissions to match the new UID/GID
    docker-php-serversideup-set-file-permissions --owner $USER_ID:$GROUP_ID

# Drop back to our unprivileged user
USER www-data

############################################
# Production Image
############################################

# Since we're calling "base", production isn't
# calling any of that permission stuff
FROM base AS production

# Copy our app files as www-data (33:33)
COPY --chown=www-data:www-data . /var/www/html

```

--------------------------------

### Custom artisan command startup script (entrypoint.d/99-my-script.sh)

Source: https://serversideup.net/open-source/docker-php/docs/customizing-the-image/adding-your-own-start-up-scripts

Shell script to run a custom artisan command at startup. Checks if the artisan file exists in $APP_BASE_DIR, runs the command, and exits with success. If the file is missing, prints an error and exits with code 1.

```shell
#!/bin/sh
# Check if the artisan file exists
if [ -f "$APP_BASE_DIR/artisan" ]; then
  # Run the custom artisan command
  php "$APP_BASE_DIR/artisan" my:custom-command
else
  # If the artisan file is not found, stop the container
  echo "❌ Artisan file not found in $APP_BASE_DIR"
  exit 1
fi

# Exit with a success code
exit 0

```

--------------------------------

### Declare S6 service dependencies (shell commands)

Source: https://serversideup.net/open-source/docker-php/docs/customizing-the-image/adding-your-own-start-up-scripts

Commands to create the dependencies.d directory and declare dependencies on 'base' and the converted entrypoint script service '10-init-webserver-config'.

```shell
mkdir -p /etc/s6-overlay/s6-rc.d/my-s6-service/dependencies.d
touch /etc/s6-overlay/s6-rc.d/my-s6-service/dependencies.d/base
touch /etc/s6-overlay/s6-rc.d/my-s6-service/dependencies.d/10-init-webserver-config

```

--------------------------------

### Bind mount local directory to /var/www/html

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/container-basics

Creates a bind mount that connects the local project directory to the container's /var/www/html directory. Changes are instantly visible inside the container, and files persist after the container stops.

```yaml
volumes:
  - ./:/var/www/html

```

--------------------------------

### Docker Compose: Build image with intl and bcmath extensions

Source: https://serversideup.net/open-source/docker-php/docs/customizing-the-image/installing-additional-php-extensions

Use this Docker Compose command to build an image with the intl and bcmath extensions. The --build flag forces a rebuild from scratch, which is good practice when changing the Dockerfile.

```bash
docker compose up --build

```

--------------------------------

### Basic production Dockerfile

Source: https://serversideup.net/open-source/docker-php/docs/deployment-and-production/packaging-your-app-for-deployment

Minimal Dockerfile that copies application code into the image with correct ownership. This is the foundation for a production image.

```dockerfile
FROM serversideup/php:8.5-fpm-nginx

# Copy your application code into the image
COPY --chown=www-data:www-data . /var/www/html

```

--------------------------------

### Laravel TrustProxies Middleware - Trust All Proxies

Source: https://serversideup.net/open-source/docker-php/docs/guide/configuring-trusted-proxies

Configure Laravel's TrustProxies middleware to trust all proxies, suitable for most setups using the Docker images since the web server has already validated them.

```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->trustProxies(at: '*');
})

```

--------------------------------

### Bring Your Own Certificate with SSL_MODE mixed

Source: https://serversideup.net/open-source/docker-php/docs/deployment-and-production/configuring-ssl

Mount your own PEM certificate and private key into the container. Set the private key file permissions to 600; incorrect permissions cause errors when loading the key.

```yaml
services:
  php:
    image: serversideup/php:8.5-fpm-nginx
    ports:
      - 80:8080
      - 443:8443
    environment:
      SSL_MODE: "mixed"
      SSL_PRIVATE_KEY_FILE: "/etc/ssl/custom/test-key.pem"
      SSL_CERTIFICATE_FILE: "/etc/ssl/custom/test.pem"
    volumes:
      - .:/var/www/html/
      - ./certs/:/etc/ssl/custom/

```

--------------------------------

### Dockerfile with multi-stage build for dev, CI, and deploy

Source: https://serversideup.net/open-source/docker-php/docs/guide/major-version-migrations

Multi-stage Dockerfile for development, CI, and production using the serversideup/php base image. It sets user/group IDs via build arguments for development, runs as root in CI, and copies files with www-data ownership for deployment.

```Dockerfile
############################################
# Base Image
############################################

# Learn more about the Server Side Up PHP Docker Images at:
# https://serversideup.net/open-source/docker-php/
FROM serversideup/php:8.4-fpm-nginx AS base

## Uncomment if you need to install additional PHP extensions
# USER root
# RUN install-php-extensions bcmath gd

############################################
# Development Image
############################################
FROM base AS development

# We can pass USER_ID and GROUP_ID as build arguments
# to ensure the www-data user has the same UID and GID
# as the user running Docker.
ARG USER_ID
ARG GROUP_ID

# Switch to root so we can set the user ID and group ID
USER root
RUN docker-php-serversideup-set-id www-data $USER_ID:$GROUP_ID  && \
    docker-php-serversideup-set-file-permissions --owner $USER_ID:$GROUP_ID
USER www-data

############################################
# CI image
############################################
FROM base AS ci

# Sometimes CI images need to run as root
USER root

############################################
# Production Image
############################################
FROM base AS deploy
COPY --chown=www-data:www-data . /var/www/html
USER www-data

```

--------------------------------

### Run linting checks locally (actionlint, shellcheck, hadolint, script tests)

Source: https://serversideup.net/open-source/docker-php/docs/getting-started/contributing

Run the same linting checks that CI runs before pushing: actionlint for workflows, ShellCheck for scripts, hadolint for Dockerfiles, and fixture tests for helper scripts. The script tests live in scripts/tests/run.sh and CI runs the same file on a GitHub runner, whose jq and yq versions can differ from your machine.

```bash
docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:latest -color

docker run --rm -v "$PWD:/repo" -w /repo koalaman/shellcheck:stable --severity=warning \
  scripts/*.sh scripts/tests/*.sh src/common/usr/local/bin/* src/s6/usr/local/bin/* .oss-scanner/run-variation $(find src -path '*entrypoint.d*' -name '*.sh')

docker run --rm -v "$PWD:/repo" -w /repo hadolint/hadolint:latest hadolint src/variations/*/Dockerfile .oss-scanner/Dockerfile

bash scripts/tests/run.sh

```
Tokens:
Raw