mirror of
https://github.com/php/frankenphp.git
synced 2026-03-24 00:52:11 +01:00
dcfdb2f068
Adds `XDG_CONFIG_HOME` and `XDG_DATA_HOME` to the example hardened image docs, otherwise Caddy will fail to use the nonexistent /home directory instead of `/data/caddy` and `/config/caddy`. Also removes an unnecessary `--chown=nonroot:nonroot`.
287 lines
9.3 KiB
Markdown
287 lines
9.3 KiB
Markdown
# Building Custom Docker Image
|
|
|
|
[FrankenPHP Docker images](https://hub.docker.com/r/dunglas/frankenphp) are based on [official PHP images](https://hub.docker.com/_/php/).
|
|
Debian and Alpine Linux variants are provided for popular architectures.
|
|
Debian variants are recommended.
|
|
|
|
Variants for PHP 8.2, 8.3, 8.4 and 8.5 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, ranging from major (e.g. `1`), minor (e.g. `1.2`) to patch versions (e.g. `1.2.3`).
|
|
- `<os>` is either `trixie` (for Debian Trixie), `bookworm` (for Debian Bookworm), or `alpine` (for the latest stable version of Alpine).
|
|
|
|
[Browse tags](https://hub.docker.com/r/dunglas/frankenphp/tags).
|
|
|
|
## How to Use The Images
|
|
|
|
Create a `Dockerfile` in your project:
|
|
|
|
```dockerfile
|
|
FROM dunglas/frankenphp
|
|
|
|
COPY . /app/public
|
|
```
|
|
|
|
Then, run these commands to build and run the Docker image:
|
|
|
|
```console
|
|
docker build -t my-php-app .
|
|
docker run -it --rm --name my-running-app my-php-app
|
|
```
|
|
|
|
## How to Tweak the Configuration
|
|
|
|
For convenience, [a default `Caddyfile`](https://github.com/php/frankenphp/blob/main/caddy/frankenphp/Caddyfile) containing
|
|
useful environment variables is provided in the image.
|
|
|
|
## How to Install More PHP Extensions
|
|
|
|
The [`docker-php-extension-installer`](https://github.com/mlocati/docker-php-extension-installer) script is provided in the base image.
|
|
Adding additional PHP extensions is straightforward:
|
|
|
|
```dockerfile
|
|
FROM dunglas/frankenphp
|
|
|
|
# add additional extensions here:
|
|
RUN install-php-extensions \
|
|
pdo_mysql \
|
|
gd \
|
|
intl \
|
|
zip \
|
|
opcache
|
|
```
|
|
|
|
## How to Install More Caddy Modules
|
|
|
|
FrankenPHP is built on top of Caddy, and all [Caddy modules](https://caddyserver.com/docs/modules/) can be used with FrankenPHP.
|
|
|
|
The easiest way to install custom Caddy modules is to use [xcaddy](https://github.com/caddyserver/xcaddy):
|
|
|
|
```dockerfile
|
|
FROM dunglas/frankenphp:builder AS builder
|
|
|
|
# Copy xcaddy in the builder image
|
|
COPY --from=caddy:builder /usr/bin/xcaddy /usr/bin/xcaddy
|
|
|
|
# CGO must be enabled to build FrankenPHP
|
|
RUN CGO_ENABLED=1 \
|
|
XCADDY_SETCAP=1 \
|
|
XCADDY_GO_BUILD_FLAGS="-ldflags='-w -s' -tags=nobadger,nomysql,nopgx" \
|
|
CGO_CFLAGS=$(php-config --includes) \
|
|
CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" \
|
|
xcaddy build \
|
|
--output /usr/local/bin/frankenphp \
|
|
--with github.com/dunglas/frankenphp=./ \
|
|
--with github.com/dunglas/frankenphp/caddy=./caddy/ \
|
|
--with github.com/dunglas/caddy-cbrotli \
|
|
# Mercure and Vulcain are included in the official build, but feel free to remove them
|
|
--with github.com/dunglas/mercure/caddy \
|
|
--with github.com/dunglas/vulcain/caddy
|
|
# Add extra Caddy modules here
|
|
|
|
FROM dunglas/frankenphp AS runner
|
|
|
|
# Replace the official binary by the one contained your custom modules
|
|
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](https://hub.docker.com/r/dunglas/frankenphp/tags?name=builder) are provided for all versions of FrankenPHP and PHP, both for Debian and Alpine.
|
|
|
|
> [!TIP]
|
|
>
|
|
> If you're using Alpine Linux and Symfony,
|
|
> you may need to [increase the default stack size](compile.md#using-xcaddy).
|
|
|
|
## Enabling the Worker Mode by Default
|
|
|
|
Set the `FRANKENPHP_CONFIG` environment variable to start FrankenPHP with a worker script:
|
|
|
|
```dockerfile
|
|
FROM dunglas/frankenphp
|
|
|
|
# ...
|
|
|
|
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:
|
|
|
|
```console
|
|
docker run -v $PWD:/app/public -p 80:80 -p 443:443 -p 443:443/udp --tty my-php-app
|
|
```
|
|
|
|
> [!TIP]
|
|
>
|
|
> The `--tty` option allows to have nice human-readable logs instead of JSON logs.
|
|
|
|
With Docker Compose:
|
|
|
|
```yaml
|
|
# compose.yaml
|
|
|
|
services:
|
|
php:
|
|
image: dunglas/frankenphp
|
|
# uncomment the following line if you want to use a custom Dockerfile
|
|
#build: .
|
|
# uncomment the following line if you want to run this in a production environment
|
|
# restart: always
|
|
ports:
|
|
- "80:80" # HTTP
|
|
- "443:443" # HTTPS
|
|
- "443:443/udp" # HTTP/3
|
|
volumes:
|
|
- ./:/app/public
|
|
- caddy_data:/data
|
|
- caddy_config:/config
|
|
# comment the following line in production, it allows to have nice human-readable logs in dev
|
|
tty: true
|
|
|
|
# Volumes needed for Caddy certificates and configuration
|
|
volumes:
|
|
caddy_data:
|
|
caddy_config:
|
|
```
|
|
|
|
## Running as a Non-Root User
|
|
|
|
FrankenPHP can run as non-root user in Docker.
|
|
|
|
Here is a sample `Dockerfile` doing this:
|
|
|
|
```dockerfile
|
|
FROM dunglas/frankenphp
|
|
|
|
ARG USER=appuser
|
|
|
|
RUN \
|
|
# Use "adduser -D ${USER}" for alpine based distros
|
|
useradd ${USER}; \
|
|
# Add additional capability to bind to port 80 and 443
|
|
setcap CAP_NET_BIND_SERVICE=+eip /usr/local/bin/frankenphp; \
|
|
# Give write access to /config/caddy and /data/caddy
|
|
chown -R ${USER}:${USER} /config/caddy /data/caddy
|
|
|
|
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:
|
|
|
|
```dockerfile
|
|
FROM dunglas/frankenphp
|
|
|
|
ARG USER=appuser
|
|
|
|
RUN \
|
|
# Use "adduser -D ${USER}" for alpine based distros
|
|
useradd ${USER}; \
|
|
# Remove default capability
|
|
setcap -r /usr/local/bin/frankenphp; \
|
|
# Give write access to /config/caddy and /data/caddy
|
|
chown -R ${USER}:${USER} /config/caddy /data/caddy
|
|
|
|
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
|
|
|
|
## Hardening Images
|
|
|
|
To further reduce the attack surface and size of your FrankenPHP Docker images, it's also possible to build them on top of a
|
|
[Google distroless](https://github.com/GoogleContainerTools/distroless) or
|
|
[Docker hardened](https://www.docker.com/products/hardened-images) image.
|
|
|
|
> [!WARNING]
|
|
> These minimal base images do not include a shell or package manager, which makes debugging more difficult.
|
|
> They are therefore recommended only for production if security is a high priority.
|
|
|
|
When adding additional PHP extensions, you will need an intermediate build stage:
|
|
|
|
```dockerfile
|
|
FROM dunglas/frankenphp AS builder
|
|
|
|
# Add additional PHP extensions here
|
|
RUN install-php-extensions pdo_mysql pdo_pgsql #...
|
|
|
|
# Copy shared libs of frankenphp and all installed extensions to temporary location
|
|
# You can also do this step manually by analyzing ldd output of frankenphp binary and each extension .so file
|
|
RUN apt-get update && apt-get install -y libtree && \
|
|
EXT_DIR="$(php -r 'echo ini_get("extension_dir");')" && \
|
|
FRANKENPHP_BIN="$(which frankenphp)"; \
|
|
LIBS_TMP_DIR="/tmp/libs"; \
|
|
mkdir -p "$LIBS_TMP_DIR"; \
|
|
for target in "$FRANKENPHP_BIN" $(find "$EXT_DIR" -maxdepth 2 -type f -name "*.so"); do \
|
|
libtree -pv "$target" | sed 's/.*── \(.*\) \[.*/\1/' | grep -v "^$target" | while IFS= read -r lib; do \
|
|
[ -z "$lib" ] && continue; \
|
|
base=$(basename "$lib"); \
|
|
destfile="$LIBS_TMP_DIR/$base"; \
|
|
if [ ! -f "$destfile" ]; then \
|
|
cp "$lib" "$destfile"; \
|
|
fi; \
|
|
done; \
|
|
done
|
|
|
|
|
|
# Distroless debian base image, make sure this is the same debian version as the base image
|
|
FROM gcr.io/distroless/base-debian13
|
|
# Docker hardened image alternative
|
|
# FROM dhi.io/debian:13
|
|
|
|
# Location of your app and Caddyfile to be copied into the container
|
|
ARG PATH_TO_APP="."
|
|
ARG PATH_TO_CADDYFILE="./Caddyfile"
|
|
|
|
# Copy your app into /app
|
|
# For further hardening make sure only writable paths are owned by the nonroot user
|
|
COPY --chown=nonroot:nonroot "$PATH_TO_APP" /app
|
|
COPY "$PATH_TO_CADDYFILE" /etc/caddy/Caddyfile
|
|
|
|
# Copy frankenphp and necessary libs
|
|
COPY --from=builder /usr/local/bin/frankenphp /usr/local/bin/frankenphp
|
|
COPY --from=builder /usr/local/lib/php/extensions /usr/local/lib/php/extensions
|
|
COPY --from=builder /tmp/libs /usr/lib
|
|
|
|
# Copy php.ini configuration files
|
|
COPY --from=builder /usr/local/etc/php/conf.d /usr/local/etc/php/conf.d
|
|
COPY --from=builder /usr/local/etc/php/php.ini-production /usr/local/etc/php/php.ini
|
|
|
|
# Caddy data dirs — must be writable for nonroot, even on a read-only root filesystem
|
|
ENV XDG_CONFIG_HOME=/config \
|
|
XDG_DATA_HOME=/data
|
|
COPY --from=builder --chown=nonroot:nonroot /data/caddy /data/caddy
|
|
COPY --from=builder --chown=nonroot:nonroot /config/caddy /config/caddy
|
|
|
|
USER nonroot
|
|
|
|
WORKDIR /app
|
|
|
|
# entrypoint to run frankenphp with the provided Caddyfile
|
|
ENTRYPOINT ["/usr/local/bin/frankenphp", "run", "-c", "/etc/caddy/Caddyfile"]
|
|
```
|
|
|
|
## Development Versions
|
|
|
|
Development versions are available in the [`dunglas/frankenphp-dev`](https://hub.docker.com/repository/docker/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.
|