Building Custom Docker Image

FrankenPHP Docker images are based on official PHP images. Debian and Alpine Linux variants are provided for popular architectures. Debian variants are recommended.

Variants for PHP 8.2 and PHP 8.3 are provided.

The tags follow this pattern: dunglas/frankenphp:<frankenphp-version>-php<php-version>-<os>

  • <frankenphp-version> and <php-version> are version numbers of FrankenPHP and PHP respectively, with specifities ranging from major (e.g. 1), minor (e.g. 1.2) to patch versions (e.g. 1.2.3).
  • <os> is either bookworm (for Debian Bookworm) or alpine (for the latest stable version of Alpine).

Browse tags.

How to Use The Images

Create a Dockerfile in your project:

  1. FROM dunglas/frankenphp
  3. COPY . /app/public

Then, run these commands to build and run the Docker image:

  1. docker build -t my-php-app .
  2. docker run -it --rm --name my-running-app my-php-app

How to Install More PHP Extensions

The docker-php-extension-installer script is provided in the base image. Adding additional PHP extensions is straightforward:

  1. FROM dunglas/frankenphp
  3. # add additional extensions here:
  4. RUN install-php-extensions \
  5.     pdo_mysql \
  6.     gd \
  7.     intl \
  8.     zip \
  9.     opcache

How to Install More Caddy Modules

FrankenPHP is built on top of Caddy, and all Caddy modules can be used with FrankenPHP.

The easiest way to install custom Caddy modules is to use xcaddy:

  1. FROM dunglas/frankenphp:builder AS builder
  3. # Copy xcaddy in the builder image
  4. COPY --from=caddy:builder /usr/bin/xcaddy /usr/bin/xcaddy
  6. # CGO must be enabled to build FrankenPHP
  7. ENV CGO_ENABLED=1 XCADDY_SETCAP=1 XCADDY_GO_BUILD_FLAGS="-ldflags '-w -s'"
  8. RUN xcaddy build \
  9.     --output /usr/local/bin/frankenphp \
  10.     --with github.com/dunglas/frankenphp=./ \
  11.     --with github.com/dunglas/frankenphp/caddy=./caddy/ \
  12.     --with github.com/dunglas/caddy-cbrotli \
  13.     # Mercure and Vulcain are included in the official build, but feel free to remove them
  14.     --with github.com/dunglas/mercure/caddy \
  15.     --with github.com/dunglas/vulcain/caddy
  16.     # Add extra Caddy modules here
  18. FROM dunglas/frankenphp AS runner
  20. # Replace the official binary by the one contained your custom modules
  21. COPY --from=builder /usr/local/bin/frankenphp /usr/local/bin/frankenphp

The builder image provided by FrankenPHP contains a compiled version of libphp. Builders images are provided for all versions of FrankenPHP and PHP, both for Debian and Alpine.

Docker images - 图1Tip

If you’re using Alpine Linux and Symfony, you may need to increase the default stack size.

Enabling the Worker Mode by Default

Set the FRANKENPHP_CONFIG environment variable to start FrankenPHP with a worker script:

  1. FROM dunglas/frankenphp
  3. # ...
  5. ENV FRANKENPHP_CONFIG="worker ./public/index.php"

Using a Volume in Development

To develop easily with FrankenPHP, mount the directory from your host containing the source code of the app as a volume in the Docker container:

  1. docker run -v $PWD:/app/public -p 80:80 -p 443:443 -p 443:443/udp --tty my-php-app

Docker images - 图2Tip

The --tty option allows to have nice human-readable logs instead of JSON logs.

With Docker Compose:

  1. # compose.yaml
  3. services:
  4.   php:
  5.     image: dunglas/frankenphp
  6.     # uncomment the following line if you want to use a custom Dockerfile
  7.     #build: .
  8.     # uncomment the following line if you want to run this in a production environment
  9.     # restart: always
  10.     ports:
  11.       - "80:80" # HTTP
  12.       - "443:443" # HTTPS
  13.       - "443:443/udp" # HTTP/3
  14.     volumes:
  15.       - ./:/app/public
  16.       - caddy_data:/data
  17.       - caddy_config:/config
  18.     # comment the following line in production, it allows to have nice human-readable logs in dev
  19.     tty: true
  21. # Volumes needed for Caddy certificates and configuration
  22. volumes:
  23.   caddy_data:
  24.   caddy_config:

Running as a Non-Root User

FrankenPHP can run as non-root user in Docker.

Here is a sample Dockerfile doing this:

  1. FROM dunglas/frankenphp
  3. ARG USER=www-data
  5. RUN \
  6.     # Use "adduser -D ${USER}" for alpine based distros
  7.     useradd -D ${USER}; \
  8.     # Add additional capability to bind to port 80 and 443
  9.     setcap CAP_NET_BIND_SERVICE=+eip /usr/local/bin/frankenphp; \
  10.     # Give write access to /data/caddy and /config/caddy
  11.     chown -R ${USER}:${USER} /data/caddy && chown -R ${USER}:${USER} /config/caddy
  13. USER ${USER}

Running With No Capabilities

Even when running rootless, FrankenPHP needs the CAP_NET_BIND_SERVICE capability to bind the web server on privileged ports (80 and 443).

If you expose FrankenPHP on a non-privileged port (1024 and above), it’s possible to run the webserver as a non-root user, and without the need for any capability:

  1. FROM dunglas/frankenphp
  3. ARG USER=www-data
  5. RUN \
  6.     # Use "adduser -D ${USER}" for alpine based distros
  7.     useradd -D ${USER}; \
  8.     # Remove default capability
  9.     setcap -r /usr/local/bin/frankenphp; \
  10.     # Give write access to /data/caddy and /config/caddy
  11.     chown -R ${USER}:${USER} /data/caddy && chown -R ${USER}:${USER} /config/caddy
  13. USER ${USER}

Next, set the SERVER_NAME environment variable to use an unprivileged port. Example: :8000

Updates

The Docker images are built:

  • when a new release is tagged
  • daily at 4 am UTC, if new versions of the official PHP images are available

Development Versions

Development versions are available in the dunglas/frankenphp-dev Docker repository. A new build is triggered every time a commit is pushed to the main branch of the GitHub repository.

The latest* tags point to the head of the main branch. Tags of the form sha-<git-commit-hash> are also available.