From c012cd6898ee7f6de27e335611c1436b493beb5f Mon Sep 17 00:00:00 2001
From: clawbot <35+clawbot@noreply.example.org>
Date: Mon, 28 Sep 2026 09:17:22 +0000
Subject: [PATCH] Document running webhooker under upaas (closes #323)

Adds a short "Running under upaas" section to the README, next to
"Running with Docker": the container port, the data volume and the
commands that create it, the environment variables upaas should set,
the health check upaas reads after a deploy, and where the first-run
admin password appears and how to reset it.

upaas bind-mounts a host directory it does not create, and a
directory made by root stops the container at its data directory
lock. The section has the operator create the directory owned by
UID 1000 before the first deploy; the image is unchanged.

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

diff --git a/README.md b/README.md
index e1289af..2a11d27 100644
--- a/README.md
+++ b/README.md
@@ -731,6 +731,60 @@ 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:
+
+- **Port:** container 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`: the address your reverse proxy connects from,
+      as the container sees it; the `remoteIP` field of each
+      `http request` log line shows it. 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