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 1/2] 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 -- 2.54.0 From 8fa7dfae533b4efcf74e37f323a3d87f64072a61 Mon Sep 17 00:00:00 2001 From: sneak Date: Mon, 28 Sep 2026 10:04:29 +0000 Subject: [PATCH 2/2] Reach the upaas app over a Docker network, not a port mapping upaas publishes every mapped port on all host interfaces, which would expose the plain-HTTP admin UI and receiver. The section now says to add no port mapping, to put the app on the reverse proxy's Docker network, and that the proxy reaches it at the upaas container name on port 8080. TRUSTED_PROXIES is the proxy's address on that network; the log hint now points at a proxied request's line, since health-check lines show ::1. Model: opus-5-5 --- README.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2a11d27..85275c4 100644 --- a/README.md +++ b/README.md @@ -736,8 +736,14 @@ credentials. [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`. +- **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 @@ -752,10 +758,10 @@ repository's `Dockerfile` and runs it. The app needs: - **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). + - `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`. -- 2.54.0