From 0c1c5344353ec74bcb8d77d7f9cde9f0b9b45493 Mon Sep 17 00:00:00 2001
From: Maurice <mauriceboe@icloud.com>
Date: Sun, 28 Jun 2026 10:23:07 +0200
Subject: [PATCH] docs(wiki): document the snap Docker + no-new-privileges
 startup failure

---
 wiki/Install-Docker-Compose.md |  2 ++
 wiki/Troubleshooting.md        | 30 ++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/wiki/Install-Docker-Compose.md b/wiki/Install-Docker-Compose.md
index c12806ac..7319c093 100644
--- a/wiki/Install-Docker-Compose.md
+++ b/wiki/Install-Docker-Compose.md
@@ -18,6 +18,8 @@ The compose file ships with several hardening options enabled by default:
 | `cap_add: [CHOWN, SETUID, SETGID]` | Adds back only the capabilities needed for the entrypoint to drop privileges to the `node` user |
 | `tmpfs: /tmp:noexec,nosuid,size=64m` | Mounts a 64 MB in-memory `/tmp`; required because the container root is read-only |
 
+> **Note (Docker from snap):** If you installed Docker via `snap` (config under `/var/snap/docker/...`), `no-new-privileges:true` will prevent the container from starting with `exec /usr/bin/dumb-init: operation not permitted`. This is a [snap/AppArmor limitation](https://bugs.launchpad.net/snapd/+bug/1908448), not a TREK issue — install Docker from the [official apt repository](https://docs.docker.com/engine/install/ubuntu/) instead, or remove `no-new-privileges`. See [Troubleshooting](Troubleshooting#container-wont-start-exec-usrbindumb-init-operation-not-permitted).
+
 ## Volumes
 
 | Host path | Container path | Contents |
diff --git a/wiki/Troubleshooting.md b/wiki/Troubleshooting.md
index dae924c8..fa70fb39 100644
--- a/wiki/Troubleshooting.md
+++ b/wiki/Troubleshooting.md
@@ -105,6 +105,36 @@ sudo chown -R 1000:1000 ./data ./uploads
 
 ---
 
+## Container won't start: "exec /usr/bin/dumb-init: operation not permitted"
+
+**Symptoms:** The container restarts in a loop and the logs show nothing but:
+
+```
+trek  | exec /usr/bin/dumb-init: operation not permitted
+trek exited with code 255 (restarting)
+```
+
+**Cause:** You are running **Docker installed from the snap** (its config lives under `/var/snap/docker/...`) *and* your compose file sets `security_opt: [no-new-privileges:true]`. The snap-packaged `dockerd` runs under its own AppArmor profile, and AppArmor refuses the `no_new_privs` privilege transition for snapped daemons. The container's very first `execve` is denied with `EPERM`, so it never starts. Confirm it in the kernel log right after a crash:
+
+```bash
+sudo dmesg -T | grep -iE 'apparmor|denied'
+# apparmor="DENIED" operation="exec" ... info="no new privs"
+```
+
+This affects **any** image, not just TREK, and is a known snap limitation ([snapd bug #1908448](https://bugs.launchpad.net/snapd/+bug/1908448)). Setting `apparmor=unconfined` on the container does **not** help — that only swaps the *container's* profile, while the denial comes from the *daemon's* (snap's) confinement, which a container-level option cannot reach.
+
+**Fix:** Install Docker from the official apt repository instead of the snap. Your data is safe as long as it lives in host bind-mounts (`./data`, `./uploads`):
+
+```bash
+sudo snap remove docker
+curl -fsSL https://get.docker.com | sudo sh   # or follow docs.docker.com/engine/install/ubuntu
+docker compose up -d
+```
+
+> **Note:** If you must stay on the snap, the only workaround is removing `no-new-privileges` from `security_opt`. The rest of the hardening (`read_only`, `cap_drop: ALL` with a minimal `cap_add`, the `noexec,nosuid` tmpfs) keeps working and carries most of the weight. See [Security Hardening](Security-Hardening).
+
+---
+
 ## Encryption key regenerated on restart — stored secrets stop working
 
 **Cause:** On every startup, TREK resolves its encryption key in this order: (1) `ENCRYPTION_KEY` env var, (2) `data/.encryption_key` file, (3) legacy `data/.jwt_secret` fallback, (4) auto-generate a fresh key. If neither the env var nor the `data/` volume is persisted — for example after recreating a container without a volume mount — a new random key is generated and all stored secrets (SMTP password, OIDC client secret, API keys, MFA TOTP seeds) become unrecoverable.