Repository navigation
Releases
Releases · 6RUN0/docker-freeunit-php
v0.4.0
The image runs without root. Migration for a derived image or a deployment is
the numbered list below; the floating trixie-php* and latest tags point at
the non-root image from this release on.
Removed
- (2) The
APPLICATION_USER/UID/GROUP/GID/DIR/CHOWNvariables: they are
ignored, the entrypoint creates no user and changes no ownership at start.
Bake the ownership of writable paths into the image (named volumes copy the
mount point owner) or own the host dir by the process uid. - (3) The library functions
setup_userandexec_as_user, and
UNIT_LIB_NO_PROVISION: a hook that calls them fails at start with "command
not found". A hook runs as the container user already; it justexecs. - The immutable tag without a version:
trixie-1.37.2-2-php*stays the
root-based 0.3.0 image. - (12) bash in the entrypoint:
docker-entrypoint.sh, the library and the
healthcheck are portable POSIX sh (/bin/sh, dash in the image). A hook in
/docker-entrypoint-hook.dis sourced by it, so a bash hook (local,
[[ ]], arrays,declare -F) stops working: rewrite it in POSIX sh,
prefix its variables with<cmd>_(nolocal) and keep onlyhandle_<cmd>
functions,<cmd>of[A-Za-z0-9_]. The handler is looked up with
command -v.
Changed
- (1) The image starts as
nonroot(uid:gid65532:65532, home
/home/nonroot): tini, the entrypoint, the Unit master and the PHP workers
run as that user and need no capability (--cap-drop=ALL, nocap_add). A
derivedDockerfileneedsUSER 0:0beforeRUN apt-getand
USER 65532:65532at the end. Any other non-root uid:gid works when its
mounts are writable for it. - (4) Do not set
applications.*.user/groupin the Unit config: an
unprivileged Unit runs its workers as its own user (it logs a warning that it
cannot use arbitrary user and group). - (5) The Unit state dir is
/run/freeunit(was the compiled
/var/lib/freeunit); with a tmpfs at/runthe configuration from
/docker-entrypoint.dis applied on every container start. An explicit
freeunitd .../freeunitd-debug ...command gets the missing--no-daemon,
--control,--pid,--statedirand--tmpdirflags; one of the last four
with another value (e.g.--statedir /var/lib/freeunit) stops the start with
an error.--version/--help/-hrun as given, without initial
configuration. - (6) Unit buffers request bodies in
/tmp(--tmpdir /tmp), where PHP keeps
its uploads and temp files by default;session.save_pathis/tmpforcli
andembed(was the root-owned/var/lib/php/sessions)./tmpmust be
writable for the process uid; underread_onlymount a host dir there
(recommended) or a tmpfs with asize. - (7) Every writable path is a mount the process uid can write:
/run(tmpfs),
/tmp, and the application's own bind mounts. The entrypoint checks
/var/run, the state dir and/tmpbefore anything else and stops with a hint
naming the missing mount.HOME(/home/nonroot, empty, 0755) may stay
read-only; an application that writes there mounts it. - (8) A listener below port 1024 needs
net.ipv4.ip_unprivileged_port_start=0
(the Docker default since Engine 20.10). - (9) Started as root (
--user 0:0): the entrypoint hands stdio to 65532 and
re-execs itself as65532:65532with no supplementary groups and
no_new_privs, logging a warning; tini (PID 1) stays root in that mode.
It needs the default capabilities or at least
CAP_SETUID/CAP_SETGID/CAP_CHOWN/CAP_KILL; without them the start stops
with an error, as does a non-root uid with group 0. The healthcheck, run as
root then, probes as the owner of the control socket. - (10) The control socket, the state dir and the generated dir belong to the
same uid as the PHP workers: code execution in PHP can reconfigure Unit until
the container restarts. The unix socket rules out SSRF, not RCE. - (11) The immutable tags carry the image version:
trixie-<freeunit-release>-php<X.Y>-v<version>(e.g.
trixie-1.37.2-2-php8.4-v0.4.0),<version>-php<X.Y>and<version>. The
release workflow refuses to run when one of them exists and creates them
last, from the attested digest, after the floating tags. - The hook files in
/docker-entrypoint-hook.dare sourced as the container
user; they must still be root-owned and not group/world-writable. - Examples: no
user/groupin the Unit configs, nocap_add;devcreates
/dataowned by 65532 in itsDockerfileinstead ofAPPLICATION_CHOWN;
cron-hookexecs supercronic without a privilege drop;web-apprenders its
TLS bundle into$ENTRYPOINT_GENERATED_DIR.
Added
ENTRYPOINT_GENERATED_DIR(/run/docker-entrypoint.d, exported to the
/docker-entrypoint.d/*.shscripts): the*.pemand*.jsona script renders
there are applied after those of/docker-entrypoint.d(certificates of both
dirs before any config, the generated config last);*.shthere are not
executed.- Library functions
drop_root_or_die,prepare_runtime_dirs,
build_unit_launch_argsand the literalsUNIT_TMP_DIR,
UNIT_NONROOT_UID/GID/HOME. test/smoke.shruns every launch mode: hardened (--read-only --cap-drop=ALL), plain, root drop (also under-t) and its refusals, an
arbitrary uid, an explicitfreeunitdcommand.
v0.3.0
Changed
- Bumped the bundled FreeUnit to
1.37.2-2(up from1.37.1-1) and recomputed
theFREEUNIT_SHA256SUMS_SHA256trust anchor. - From
1.37.2-2upstream lists packages inSHA256SUMSas
<ver>.<suite>instead of<ver>~<suite>. The build and the bump bot accept
both forms, so aFREEUNIT_RELEASEoverride to an older release still builds;
a package missing fromSHA256SUMSin both forms fails the build.
v0.2.0
Changed
- Bumped the bundled FreeUnit to
1.37.1(1.37.1-1, up from1.36.0-1) and
recomputed theFREEUNIT_SHA256SUMS_SHA256trust anchor. Upstream dropped the
-buildNsuffix from its release tags, so the immutable image tag of this
release istrixie-1.37.1-php<X.Y>. examples/cron-hook: supercronicv0.2.51(up fromv0.2.46).- The FreeUnit bump bot (
check-upstream.yml) no longer opens a PR when the
release marked Latest upstream ships an older.debversion than the pinned
one; an equal version (a rebuild under a new tag) is still bumped.
v0.1.0
Changed
- Bumped the bundled FreeUnit to
1.36.0-build1(1.36.0-1, up from1.35.6-1)
and recomputed theFREEUNIT_SHA256SUMS_SHA256trust anchor. Unlike the last
few refreshes, this is a real upstream version bump — the bundled FreeUnit
moves from 1.35.6 to 1.36.0, not a rebuild of the same package.
v0.0.9
Changed
- Bumped the bundled FreeUnit
.debrelease to1.35.6-build5and recomputed the
FREEUNIT_SHA256SUMS_SHA256trust anchor. Upstream re-published the same
1.35.6-1package under a new release tag, so the bundled FreeUnit and PHP
versions are unchanged — this is a rebuild-only refresh.
v0.0.8
Added
.trivyignorelisting the HIGH/CRITICAL CVEs in the Debian trixie base and the
sury PHP / image-codec stack that have no upstream fix (none are in FreeUnit's
own.debpackages, and none are resolvable by theapt full-upgradethe build
already runs), somake scanand the CI scan surface only new, actionable
findings instead of a permanent unfixable backlog.
Changed
- Bumped the bundled FreeUnit
.debrelease to1.35.6-build4and recomputed the
FREEUNIT_SHA256SUMS_SHA256trust anchor. Upstream re-published the same
1.35.6-1package under a new release tag, so the bundled FreeUnit and PHP
versions are unchanged — this is a rebuild-only refresh.
v0.0.7
Changed
- Bumped the bundled FreeUnit
.debrelease to1.35.6-build3and recomputed the
FREEUNIT_SHA256SUMS_SHA256trust anchor. Upstream re-published the same
1.35.6-1package under a new release tag, so the bundled FreeUnit and PHP
versions are unchanged — this is a rebuild-only refresh.
v0.0.6
Changed
- FreeUnit rebrand (breaking for downstream images). Upstream renamed its
Debian packages and on-disk identity fromunit*tofreeunit*, and the image
follows suit: the daemon isfreeunitd/freeunitd-debug, the state dir
/var/lib/freeunit, the control socket/var/run/control.freeunit.sock, the log
/var/log/freeunit.log, and the default application user/groupfreeunit(was
unit). Downstream images must move anyconfig.jsonuser/groupkeys and
any custom launch command fromunit/unitdtofreeunit/freeunitd; the
reusable entrypoint library keeps its function names andUNIT_*/APPLICATION_*
variable identifiers, so hooks that only call the documented API are unaffected. - Bumped the bundled FreeUnit
.debrelease to1.35.6-build2(1.35.6-1) and
recomputed theFREEUNIT_SHA256SUMS_SHA256trust anchor. - The brand identity is single-sourced as Dockerfile
ARGs mirroring the upstream
packaging vocabulary (BRAND,RUNTIME,RUNDIR,BRAND_TITLE,HOMEPAGE,
DOCS_URL). They default tofreeunit//var/runand the build now asserts the
installed binary's compiled paths matchRUNTIME/RUNDIR, so a future upstream
identity change fails the build instead of shipping an image whose entrypoint
manages paths the daemon does not use. - The default launch command moved out of the Dockerfile
CMDinto the entrypoint,
and theHEALTHCHECKis now a script (/docker-healthcheck.sh), so the binary
name and control-socket path stay single-sourced fromdocker-entrypoint-common.sh
instead of being duplicated in an exec-form instruction that cannot expand a
build ARG.
v0.0.5
Added
examples/grew into a capability-coverage set:dev(a live-mounted
development loop writing to a persistent state volume as the unprivileged app
user),routing(multiple apps behind path routes, static-asset serving, and a
per-app PHPmemory_limit), andweb-app(HTTPS from an entrypoint-generated
self-signed certificate, with an HTTP-to-HTTPS redirect), alongside the existing
basicandcron-hook. Each example is a self-contained subdirectory with its
own README.make test-examples: an examples gate that statically lints every example's
compose file for the capability-hardening block (cap_drop,no-new-privileges,
SETUID,SETGID), then builds, runs, and asserts each example end to end
against the just-built image.make help: a self-documenting target list parsed from the##-prefixed
comment annotations on the targets themselves.
Changed
- The
cron-hookexample fires its task every second using supercronic's
seven-field (seconds) crontab syntax, so the example and its test no longer wait
out a full minute for a tick. - CI asserts the PHP build matrix is in sync across
ci.yml,release.yml,
security-scan.yml, andcheck-upstream.yml's completeness gate against the
Makefile'sPHP_VERSIONS, failing the lint job on any drift. release.ymlguards each Dockerfile-ARG extraction, failing loudly rather than
pushing a malformed tag if an ARG line format ever drifts.- Repository hygiene: added
.gitattributes, tightened.editorconfig, and
ignored thedocs/superpowers/working notes.
Fixed
- Documentation: corrected the deb.sury.org pin priority described in
CLAUDE.md
(990, not 1001 — below 1000 so a compromised mirror cannot force a downgrade) and
the stale crontab field-count comments in the examples test, aligning the docs
with the shippedDockerfileand crontab.
v0.0.4
Added
- Extensible entrypoint hook system: a child image adds a launch mode by dropping
ahandle_<command>hook into/docker-entrypoint-hook.d/(sourced and
ownership-vetted as root before any privilege drop), and the entrypoint became a
thin dispatcher over a reusable core library (docker-entrypoint-common.sh) of
logging, daemon lifecycle, config appliers, privilege drop, and user
provisioning. Downstream images inherit every base robustness/security fix
without overwriting/docker-entrypoint.sh. examples/cron-hook/: an example of the hook system — one image runs in two
roles, the Unit web server and a long-livedsupercroniccron runner, selected
per container by the command (supercronicis pinned and SHA256-verified).test/entrypoint-lib.shgained checks for the hook dispatch contract
(dispatch_handler), theexec_as_userprivilege drop,setup_userid
validation and idempotency, thedir_has_contentempty/non-empty boundary, and
newline-less / non-numeric pidfiles. The host-side CLI parser and image build
shared by both test drivers were extracted intotest/lib.sh.
Changed
apply_confignow warns when more than one*.jsonis present in
/docker-entrypoint.d, sincePUT /configreplaces the whole configuration and
only the lexically-last file survives.wait_for_control_socketbounds each probe withcurl --max-time, and
run_entrypoint_scriptsnow reports which user script failed.examples/reorganised so each example is a self-contained subdirectory
(examples/basic/,examples/cron-hook/) with an indexREADME.md.- CI pins ShellCheck to the version used locally — the runner's bundled one
flagged false positives on the library's optional-argument and
trap/dispatch-invoked functions — and now lints each example'sREADME.md.
Fixed
- A child-hook
handle_<cmd>that exits non-zero no longer aborts the entrypoint
silently underset -ebefore its diagnostic. Dispatch moved into
dispatch_handler, which reports both a non-zero exit and a return-without-exec
with an actionable message. stop_unitno longer skipskill -TERMwhen the pidfile has no trailing
newline (readreturns non-zero at EOF even after assigning the value). The new
read_pidhelper decouples the value fromread's exit status and ignores a
non-numeric pid, so a corrupt pidfile cannot become a broad kill.dir_has_contenttreats an existing-but-unreadable directory as an error rather
than "empty", so a transientEACCESon the state dir cannot trigger a
re-initialisation over a populated state.
Security
exec_as_usernow passessetpriv --no-new-privs, so a child-image hook's
privilege drop is irreversible inside the image even if the operator omits
--security-opt=no-new-privileges.- The first-run failure wipe (
find … -delete) gained-xdev, so it stops at
filesystem boundaries and never deletes through a host volume bind-mounted
inside/var/lib/unit. apply_certificatesvalidates the bundle name to[A-Za-z0-9._-], so a crafted
*.pemfilename cannot retarget the control-APIPUTat another endpoint.