From 7ed158844361261704426aa62c303a6154ccf1b1 Mon Sep 17 00:00:00 2001
From: clawbot <35+clawbot@noreply.example.org>
Date: Mon, 28 Sep 2026 12:30:32 +0200
Subject: [PATCH] Document running webhooker under upaas (closes #323)

Adds a "Running under upaas" section to the README: add no port
mapping, since upaas publishes mapped ports on every host interface,
and put the app on the reverse proxy's Docker network instead; one
data volume at /var/lib/webhooker, created owned by UID 1000 before
the first deploy; WEBHOOKER_ENVIRONMENT and TRUSTED_PROXIES; the
health check upaas reads 60 seconds after a deploy; and where the
first-run admin password appears and how to reset it.

upaas bind-mounts a host directory it never creates, and one made by
root stops the container at its data directory lock. The documented
creation step removes that; the image is unchanged.

Model: opus-5-5
---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/README.md b/README.md
index e1289af..85275c4 100644
--- a/README.md
+++ b/README.md
@@ -731,6 +731,66 @@ listing the directory and learning your webhook UUIDs from the
 `events-{uuid}.db` filenames — not the barrier protecting the
 credentials.
 
+### Running under upaas
+
+[upaas](https://git.eeqj.de/sneak/upaas) builds the image from this
+repository's `Dockerfile` and runs it. The app needs:
+
+- **Network and port:** add no port mapping in upaas. upaas publishes
+  every mapped port on all interfaces of the host
+  ([upaas issue 113](https://git.eeqj.de/sneak/upaas/issues/113)),
+  which would put the plain-HTTP admin UI and receiver there. Instead,
+  set the app's Docker Network in upaas to your reverse proxy's Docker
+  network; the proxy then reaches the app at `upaas-` followed by the
+  app name, port `8080`. Leave `PORT` unset: the image's health check
+  probes `8080`.
+- **Volume:** one host directory mounted at `/var/lib/webhooker`.
+  upaas bind-mounts the host path it is given and does not create it,
+  and the container does not start unless UID 1000 owns it (see
+  [Running with Docker](#running-with-docker)). Create it before the
+  first deploy:
+
+    ```bash
+    mkdir -p /path/to/data
+    chown 1000:1000 /path/to/data
+    chmod 750 /path/to/data
+    ```
+
+- **Environment variables:**
+    - `WEBHOOKER_ENVIRONMENT=prod`
+    - `TRUSTED_PROXIES`: your reverse proxy's address on that Docker
+      network. The `remoteIP` field of the `http request` log line for a
+      request that came through the proxy shows it; the health check's
+      own lines show `::1`. See [Trusted proxies](#trusted-proxies).
+    - Leave `BIND_ADDRESS` and `DATA_DIR` unset: the image sets
+      `BIND_ADDRESS` to `0.0.0.0`, and `DATA_DIR` defaults to
+      `/var/lib/webhooker`.
+    - Everything else is optional; see [Configuration](#configuration).
+- **Health check:** the image's own, which requests
+  `/.well-known/healthcheck`. upaas reads the container's health 60
+  seconds after a deploy and marks the deploy failed unless it is
+  `healthy`.
+- **First run:** the first start prints the `admin` password once, in
+  the banner described under [The admin account](#the-admin-account),
+  to the container's log. upaas names the container `upaas-` followed
+  by the app name, so for an app named `webhooker`:
+
+    ```bash
+    docker logs upaas-webhooker
+    ```
+
+  If the password is lost, stop the container, set a new password with
+  the app's own image and volume, and start it again (see
+  [Recovering a lost admin password](#recovering-a-lost-admin-password)):
+
+    ```bash
+    docker stop upaas-webhooker
+    docker run --rm --volumes-from upaas-webhooker \
+        "$(docker inspect -f '{{.Image}}' upaas-webhooker)" \
+        /app/webhooker resetpw -generate admin
+    docker start upaas-webhooker
+    ```
+
 ## Deployment behind a reverse proxy
 
 webhooker terminates no TLS of its own. It serves plaintext HTTP and