Mount PHP's session config, the one path the entrypoint cannot write

The real first run of this play did not fail on a transition. The journal shows
the entrypoint dying on every attempt:

    nextcloud[302063]: => Configuring PHP session handler...
    nextcloud[302063]: /entrypoint.sh: 121: cannot create
      /usr/local/etc/php/conf.d/redis-session.ini: Permission denied

With REDIS_HOST set, the entrypoint generates PHP's session-handler config on
every start, and the target directory belongs to the image's root: the php base
image does `mkdir -p "$PHP_INI_DIR/conf.d"` with no chown. The uid this container
runs as has no write bit on it, the entrypoint exits 2 before Apache is reached,
Restart=always retries that, and systemd's start limit turns it into a `failed`
unit. Nothing in that shape says "permissions": the symptom is a unit state and a
message that only exists in journalctl.

The container now mounts a host-owned file over that exact path. A bind-mounted
file replaces the directory entry, so the directory's ownership stops mattering
and the write lands on podman_user. The role templates the five lines the
entrypoint would have written, so a refused write is no longer fatal either --
PHP still gets Redis sessions instead of a crash loop.

This also corrects a reading of the previous run that this play got wrong and
documented wrongly: `activating` is not evidence of a healthy start. A
crash-looping container spends its time `activating` between restarts, so the
earlier "reports a healthy start as a failure" comment and commit message were
describing a start that was in fact failing. The wait is still right -- it stops
promptly at a terminal state and hands over to a rescue that has the logs -- but
its comment now says what it actually buys.

Apache's own runtime directories need none of this, and the php base image is why:
it chowns /var/run/apache2, /var/lock/apache2 and /var/log/apache2 to www-data and
chmods them 1777, so only the session file was ever going to bite. The readme
gains a section on it, the diagnostic commands the play now collects, and a note
that the uid mapping is not to be derived from a `docker exec id -u` of 0.
This commit is contained in:
tanshu committed 2026-10-16 11:45:37 +05:30
1 parent 90b1149413
commit 1038037e45
5 files changed
+209 -31

No files matched your search

+17 -4
View File
@@ -42,16 +42,29 @@ network_name: "{{ container_name }}"
host_directory: "{{ podman_data_dir }}/{{ container_name }}"
webroot: /var/www/html
# The uid the *server* writes as: the image's entrypoint starts as container-root,
# rsyncs the code in with --chown www-data:www-data, and Apache then drops to
# www-data. `docker exec nextcloud id -u` reports 0, which is misleading
# (docs/podman-compat-audit.md §3.2).
# The uid the *server* writes as: 33 is www-data, which owns the webroot, because
# the entrypoint rsyncs the code in with --chown www-data:www-data and Apache runs
# its workers as that account. `docker exec nextcloud id -u` reported 0 on the old
# host, because the entrypoint drops privileges after starting — do not derive the
# mapping from that number (docs/podman-compat-audit.md §3.2).
app_uid: 33
app_gid: 33
# The port Apache listens on inside the container, and the one Caddy proxies to.
container_port: 80
# PHP's session-handler config, and the one path in the image this deployment has
# to write to. The entrypoint generates the file from REDIS_HOST on every start,
# but its target directory (`/usr/local/etc/php/conf.d`) is created by root in the
# php base image with no chown, so the uid this container runs as cannot create a
# file inside it. Mounting a host-owned file over that exact path is what gives
# the write somewhere it is allowed to land, and the template below keeps the
# image's own content in it so a refused write is not fatal either. See readme.md,
# "The PHP session file".
php_conf_dir: "{{ host_directory }}/php-conf.d"
php_session_ini: "{{ php_conf_dir }}/redis-session.ini"
php_session_ini_mount: /usr/local/etc/php/conf.d/redis-session.ini
# POSTGRES_* and REDIS_HOST are read by the entrypoint on every start — REDIS_HOST
# in particular rewrites PHP's session handler config — and POSTGRES_PASSWORD is in
# there, so it goes in this 0600 file rather than in the world-readable unit.