Skip to content

Releases

v0.4.0

Choose a tag to compare

@github-actions github-actions released this 09 Nov 19:49

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/CHOWN variables: 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_user and exec_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 just execs.
  • 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.d is sourced by it, so a bash hook (local,
    [[ ]], arrays, declare -F) stops working: rewrite it in POSIX sh,
    prefix its variables with <cmd>_ (no local) and keep only handle_<cmd>
    functions, <cmd> of [A-Za-z0-9_]. The handler is looked up with
    command -v.

Changed

  • (1) The image starts as nonroot (uid:gid 65532: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, no cap_add). A
    derived Dockerfile needs USER 0:0 before RUN apt-get and
    USER 65532:65532 at the end. Any other non-root uid:gid works when its
    mounts are writable for it.
  • (4) Do not set applications.*.user / group in 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 /run the configuration from
    /docker-entrypoint.d is applied on every container start. An explicit
    freeunitd ... / freeunitd-debug ... command gets the missing --no-daemon,
    --control, --pid, --statedir and --tmpdir flags; one of the last four
    with another value (e.g. --statedir /var/lib/freeunit) stops the start with
    an error. --version / --help / -h run 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_path is /tmp for cli
    and embed (was the root-owned /var/lib/php/sessions). /tmp must be
    writable for the process uid; under read_only mount a host dir there
    (recommended) or a tmpfs with a size.
  • (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 /tmp before 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 as 65532:65532 with 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.d are sourced as the container
    user; they must still be root-owned and not group/world-writable.
  • Examples: no user/group in the Unit configs, no cap_add; dev creates
    /data owned by 65532 in its Dockerfile instead of APPLICATION_CHOWN;
    cron-hook execs supercronic without a privilege drop; web-app renders its
    TLS bundle into $ENTRYPOINT_GENERATED_DIR.

Added

  • ENTRYPOINT_GENERATED_DIR (/run/docker-entrypoint.d, exported to the
    /docker-entrypoint.d/*.sh scripts): the *.pem and *.json a script renders
    there are applied after those of /docker-entrypoint.d (certificates of both
    dirs before any config, the generated config last); *.sh there are not
    executed.
  • Library functions drop_root_or_die, prepare_runtime_dirs,
    build_unit_launch_args and the literals UNIT_TMP_DIR,
    UNIT_NONROOT_UID/GID/HOME.
  • test/smoke.sh runs every launch mode: hardened (--read-only --cap-drop=ALL), plain, root drop (also under -t) and its refusals, an
    arbitrary uid, an explicit freeunitd command.

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 09 Nov 15:06

Changed

  • Bumped the bundled FreeUnit to 1.37.2-2 (up from 1.37.1-1) and recomputed
    the FREEUNIT_SHA256SUMS_SHA256 trust anchor.
  • From 1.37.2-2 upstream lists packages in SHA256SUMS as
    <ver>.<suite> instead of <ver>~<suite>. The build and the bump bot accept
    both forms, so a FREEUNIT_RELEASE override to an older release still builds;
    a package missing from SHA256SUMS in both forms fails the build.

v0.2.0

Choose a tag to compare

@github-actions github-actions released this 02 Nov 19:14

Changed

  • Bumped the bundled FreeUnit to 1.37.1 (1.37.1-1, up from 1.36.0-1) and
    recomputed the FREEUNIT_SHA256SUMS_SHA256 trust anchor. Upstream dropped the
    -buildN suffix from its release tags, so the immutable image tag of this
    release is trixie-1.37.1-php<X.Y>.
  • examples/cron-hook: supercronic v0.2.51 (up from v0.2.46).
  • The FreeUnit bump bot (check-upstream.yml) no longer opens a PR when the
    release marked Latest upstream ships an older .deb version than the pinned
    one; an equal version (a rebuild under a new tag) is still bumped.

v0.1.0

Choose a tag to compare

@github-actions github-actions released this 17 Jul 10:06

Changed

  • Bumped the bundled FreeUnit to 1.36.0-build1 (1.36.0-1, up from 1.35.6-1)
    and recomputed the FREEUNIT_SHA256SUMS_SHA256 trust 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

Choose a tag to compare

@github-actions github-actions released this 16 Jul 15:49

Changed

  • Bumped the bundled FreeUnit .deb release to 1.35.6-build5 and recomputed the
    FREEUNIT_SHA256SUMS_SHA256 trust anchor. Upstream re-published the same
    1.35.6-1 package under a new release tag, so the bundled FreeUnit and PHP
    versions are unchanged — this is a rebuild-only refresh.

v0.0.8

Choose a tag to compare

@github-actions github-actions released this 10 Jul 06:12

Added

  • .trivyignore listing 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 .deb packages, and none are resolvable by the apt full-upgrade the build
    already runs), so make scan and the CI scan surface only new, actionable
    findings instead of a permanent unfixable backlog.

Changed

  • Bumped the bundled FreeUnit .deb release to 1.35.6-build4 and recomputed the
    FREEUNIT_SHA256SUMS_SHA256 trust anchor. Upstream re-published the same
    1.35.6-1 package under a new release tag, so the bundled FreeUnit and PHP
    versions are unchanged — this is a rebuild-only refresh.

v0.0.7

Choose a tag to compare

@github-actions github-actions released this 28 Jun 12:51

Changed

  • Bumped the bundled FreeUnit .deb release to 1.35.6-build3 and recomputed the
    FREEUNIT_SHA256SUMS_SHA256 trust anchor. Upstream re-published the same
    1.35.6-1 package under a new release tag, so the bundled FreeUnit and PHP
    versions are unchanged — this is a rebuild-only refresh.

v0.0.6

Choose a tag to compare

@github-actions github-actions released this 17 Jun 09:34

Changed

  • FreeUnit rebrand (breaking for downstream images). Upstream renamed its
    Debian packages and on-disk identity from unit* to freeunit*, and the image
    follows suit: the daemon is freeunitd/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/group freeunit (was
    unit). Downstream images must move any config.json user/group keys and
    any custom launch command from unit/unitd to freeunit/freeunitd; the
    reusable entrypoint library keeps its function names and UNIT_*/APPLICATION_*
    variable identifiers, so hooks that only call the documented API are unaffected.
  • Bumped the bundled FreeUnit .deb release to 1.35.6-build2 (1.35.6-1) and
    recomputed the FREEUNIT_SHA256SUMS_SHA256 trust 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 to freeunit//var/run and the build now asserts the
    installed binary's compiled paths match RUNTIME/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 CMD into the entrypoint,
    and the HEALTHCHECK is now a script (/docker-healthcheck.sh), so the binary
    name and control-socket path stay single-sourced from docker-entrypoint-common.sh
    instead of being duplicated in an exec-form instruction that cannot expand a
    build ARG.

v0.0.5

Choose a tag to compare

@github-actions github-actions released this 09 Jun 17:53

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 PHP memory_limit), and web-app (HTTPS from an entrypoint-generated
    self-signed certificate, with an HTTP-to-HTTPS redirect), alongside the existing
    basic and cron-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-hook example 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, and check-upstream.yml's completeness gate against the
    Makefile's PHP_VERSIONS, failing the lint job on any drift.
  • release.yml guards 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 the docs/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 shipped Dockerfile and crontab.

v0.0.4

Choose a tag to compare

@github-actions github-actions released this 09 Jun 10:10

Added

  • Extensible entrypoint hook system: a child image adds a launch mode by dropping
    a handle_<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-lived supercronic cron runner, selected
    per container by the command (supercronic is pinned and SHA256-verified).
  • test/entrypoint-lib.sh gained checks for the hook dispatch contract
    (dispatch_handler), the exec_as_user privilege drop, setup_user id
    validation and idempotency, the dir_has_content empty/non-empty boundary, and
    newline-less / non-numeric pidfiles. The host-side CLI parser and image build
    shared by both test drivers were extracted into test/lib.sh.

Changed

  • apply_config now warns when more than one *.json is present in
    /docker-entrypoint.d, since PUT /config replaces the whole configuration and
    only the lexically-last file survives.
  • wait_for_control_socket bounds each probe with curl --max-time, and
    run_entrypoint_scripts now reports which user script failed.
  • examples/ reorganised so each example is a self-contained subdirectory
    (examples/basic/, examples/cron-hook/) with an index README.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's README.md.

Fixed

  • A child-hook handle_<cmd> that exits non-zero no longer aborts the entrypoint
    silently under set -e before its diagnostic. Dispatch moved into
    dispatch_handler, which reports both a non-zero exit and a return-without-exec
    with an actionable message.
  • stop_unit no longer skips kill -TERM when the pidfile has no trailing
    newline (read returns non-zero at EOF even after assigning the value). The new
    read_pid helper decouples the value from read's exit status and ignores a
    non-numeric pid, so a corrupt pidfile cannot become a broad kill.
  • dir_has_content treats an existing-but-unreadable directory as an error rather
    than "empty", so a transient EACCES on the state dir cannot trigger a
    re-initialisation over a populated state.

Security

  • exec_as_user now passes setpriv --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_certificates validates the bundle name to [A-Za-z0-9._-], so a crafted
    *.pem filename cannot retarget the control-API PUT at another endpoint.