Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: stop advising a non-root user for the container

Yudhi Armyndharis0062e7120441
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 59683fb06..894f9c439 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -1129,18 +1129,21 @@ npm run migration:run:main
**Solutions:**
-```bash
-# Check current permissions
-ls -la ./data/
-
-# Fix ownership (use your user ID)
-sudo chown -R $(id -u):$(id -g) ./data/
+The entrypoint starts as root, re-owns `/app/data` to the `openwa` user on every start, and then
+drops privileges with `gosu`. Keep that path intact:
+
+- Do not set `user:` on `openwa-api` (or `--user` on `docker run`). The entrypoint then cannot
+ `chown` or drop privileges, exits, and the container restarts in a loop.
+- Keep the `CHOWN`, `DAC_OVERRIDE`, `FOWNER`, `SETGID` and `SETUID` entries under `cap_add` in
+ `docker-compose.yml`; the `chown` and the `gosu` drop need them.
+- A `chown` of the host directory is not a fix: the entrypoint re-owns `/app/data` at the next start.
+- If the error persists on a bind mount, the host filesystem is refusing the `chown` (NFS with
+ `root_squash`, some rootless or SMB setups) or SELinux is denying access (add `:z` to the mount).
+ Use the named volume from the shipped `docker-compose.yml` instead.
-# Or use Docker's user mapping
-# docker-compose.yml
-services:
- openwa-api:
- user: "1000:1000" # Your UID:GID
+```bash
+# Look for the failing chown in the startup output
+docker compose logs openwa-api | head -20
```
### Issue: Container Networking
diff --git a/docs/13-horizontal-scaling.md b/docs/13-horizontal-scaling.md
index 4f2071194..0ec8225ca 100644
--- a/docs/13-horizontal-scaling.md
+++ b/docs/13-horizontal-scaling.md
@@ -380,10 +380,11 @@ spec:
# OS-level containment is the second half of the plugin sandbox boundary (see docs/23-plugin-
# sandboxing.md). Without it a worker_thread plugin that abuses Node built-ins (fs, net) runs with
# the same privileges as the API and can read host files / open raw sockets outside the capability
- # model. The shipped Docker image already runs read-only + non-root + cap_drop:ALL; the manifest
- # below mirrors that so a k8s deploy is not silently weaker.
+ # model. The shipped compose file runs the image read-only + cap_drop:ALL, and the node process
+ # runs as the non-root openwa user; the manifest below mirrors that so a k8s deploy is not
+ # silently weaker. Do NOT add runAsNonRoot: the entrypoint starts as root to chown /app/data,
+ # then drops to openwa via gosu (same as charts/openwa/values.yaml).
securityContext:
- runAsNonRoot: true
fsGroup: 1000
containers:
- name: openwa
@@ -414,6 +415,8 @@ spec:
allowPrivilegeEscalation: false
capabilities:
drop: ['ALL']
+ # Only for the root entrypoint's chown and the gosu privilege drop.
+ add: ['CHOWN', 'DAC_OVERRIDE', 'FOWNER', 'SETGID', 'SETUID']
resources:
requests:
memory: '512Mi'