compose.yaml is the self-host profile: one file, started with docker compose up -d. This page follows that file and .env.example; both are the reference when they change.
Use the agent with your instance like with the hosted one: pair with
--server https://<your app host>. An agent paired with one server can also be paired with another; pass --server to webhooktrap agent when it is paired with several.What runs
The images are
ghcr.io/jiordiviera/webhooktrap, ghcr.io/jiordiviera/webhooktrap-runner and ghcr.io/jiordiviera/webhooktrap-postgres. Every service runs read-only where it can, with all capabilities dropped and no-new-privileges. PostgreSQL and Valkey are on an internal network with no internet access.
The reference size is 2 vCPU and 4 GB of memory.
Before you start
1
Pick the image version
Set
WEBHOOKTRAP_VERSION in .env. Compose refuses to start without it, and every image uses it. Images are published for each commit on the v2 branch, tagged with the commit SHA. Use a fixed tag, never latest.2
Choose three host names
The app, the capture host and the realtime host are separate names, for example
app.example.com, in.example.com and ws.example.com, all pointing at the server. The capture host serves only /c/…; the app host never serves /c/….3
Write the secrets as files
No secret goes in
.env. Each is a file in ./secrets/, mounted as a Compose secret and read by the image’s entrypoint.These may be empty files:
mail_password, pulsesend_api_key, github_client_secret, google_client_secret, error_tracker_dsn. An empty OAuth secret turns that sign-in method off.Ownership: postgres_password and backup_cipher_pass are root:999, mode 0440. Every other file is root:33, mode 0440.4
Write .env
.env.example lists every variable name, without values. For self-host, set at least:WEBHOOKTRAP_VERSION;WEBHOOKTRAP_INSTANCE=selfhost;APP_URL,APP_HOST,CAPTURE_HOST,WS_HOST,CAPTURE_PUBLIC_ORIGIN,REVERB_PUBLIC_HOST;POSTGRES_DB,POSTGRES_USERand the matchingDB_*names;- the TLS variables of the mode you choose, below.
GUEST_MODE=false turns guest sessions off on your instance.TLS
- Built-in TLS (TLS_MODE=auto)
- Behind your proxy (TLS_MODE=off)
The default. FrankenPHP gets certificates itself.
SERVER_NAME: your three host names;CADDY_AUTO_HTTPS=on;PROXY_TRUST_MODE=none.
BIND_ADDRESS (default 0.0.0.0).Start
migrate runs first; app, reverb, horizon and scheduler wait for it. Then open APP_URL and create the first account at /register.
The runner token
runner needs a token issued by the app. Once the app is up:
-T keeps stderr out of the file. runner:token also takes --list and --revoke=<name>; run it again to rotate. With TLS_MODE=auto, add http://app:8080 to SERVER_NAME, because the runner reaches the app on that name.
The runner sends to public addresses only (RUNNER_GUARD_CEILING=public). RUNNER_GUARD_CEILING=allowlist with RUNNER_ALLOWLIST_FILE limits it to the host:port, host:from-to or cidr:port lines of a file in ./runner/.
Backups and upgrades
- The default backup repository is a volume on the same disk. That is not a disaster backup: set
BACKUP_REPO_TYPEtos3(with theBACKUP_S3_*variables) orsftp. - A full backup runs daily at
BACKUP_FULL_SCHEDULE(UTCHH:MM, default02:30), keptBACKUP_RETENTION_FULLdays (default 14). WAL is archived continuously. - With
BACKUP_BEFORE_MIGRATEon, a backup runs before every migration. - Restore into a stopped stack with an empty
pgdatavolume:docker compose run --rm backup restore, optionally with--target-time=…. - To upgrade, change
WEBHOOKTRAP_VERSIONand rundocker compose up -d. Migrations stay backward-compatible for one release, so rolling the image back needs no schema rollback.