Skip to content

docs: improve Dockerfile for hardened images #2270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dunglas wants to merge 4 commits into
base: main
Choose a base branch
from
+31 −43
Open

docs: improve Dockerfile for hardened images #2270

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
70ad81d
docs: fix Mercure support with Docker hardened images
dunglas Mar 11, 2026
6baeaad
harden
dunglas Mar 12, 2026
23aaaad
Apply suggestions from code review
dunglas Mar 24, 2026
15d2892
use heredoc syntax
dunglas Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 31 additions & 43 deletions docs/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,13 +158,14 @@ FROM dunglas/frankenphp

ARG USER=appuser

RUN \
RUN <<-EOF
# Use "adduser -D ${USER}" for alpine based distros
useradd ${USER}; \
useradd ${USER}
# Add additional capability to bind to port 80 and 443
setcap CAP_NET_BIND_SERVICE=+eip /usr/local/bin/frankenphp; \
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
EOF

USER ${USER}
```
Expand All @@ -182,13 +183,14 @@ FROM dunglas/frankenphp

ARG USER=appuser

RUN \
RUN <<-EOF
# Use "adduser -D ${USER}" for alpine based distros
useradd ${USER}; \
useradd ${USER}
# Remove default capability
setcap -r /usr/local/bin/frankenphp; \
setcap -r /usr/local/bin/frankenphp
# Give write access to /config/caddy and /data/caddy
chown -R ${USER}:${USER} /config/caddy /data/caddy
EOF

USER ${USER}
```
Expand Down Expand Up @@ -223,58 +225,44 @@ 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
RUN <<-EOF
apt-get update
apt-get install -y --no-install-recommends libtree
mkdir -p /tmp/libs
for target in $(which frankenphp) \
$(find "$(php -r 'echo ini_get("extension_dir");')" -maxdepth 2 -name "*.so"); do
libtree -pv "$target" 2>/dev/null | grep -oP '(?:── )\K/\S+(?= \[)' | while IFS= read -r lib; do
[ -f "$lib" ] && cp -n "$lib" /tmp/libs/
done
done
EOF


# Distroless Debian base image, make sure this matches the Debian version of the builder
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
# Config and 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 /data
COPY --from=builder --chown=nonroot:nonroot /config /config

USER nonroot
# Copy your app (kept root-owned) and Caddyfile
COPY . /app
COPY Caddyfile /etc/caddy/Caddyfile

USER nonroot
WORKDIR /app

# entrypoint to run frankenphp with the provided Caddyfile
ENTRYPOINT ["/usr/local/bin/frankenphp", "run", "-c", "/etc/caddy/Caddyfile"]
ENTRYPOINT ["/usr/local/bin/frankenphp", "run", "--config", "/etc/caddy/Caddyfile"]
```

## Development Versions
Expand Down