Deployment
Getting one instance running in production. The app is designed to run as a single-tenant, self-hostable unit (see ARCHITECTURE-DIRECTION.md). Once it runs, OPERATIONS.md covers keeping it running (reverse proxy examples, backup and restore, upgrades and rollback, monitoring, secret rotation) and PRIVACY.md says what it stores and logs about callers.
Quick start (local evaluation only)
Section titled “Quick start (local evaluation only)”docker-compose.yml runs the single app service and persists the JSON store in a named volume:
docker compose up --build # http://127.0.0.1:5001Without a .env this runs open: no editor login, and webhooks anyone can call (the
log says so with a SECURITY: line on every start). The port is published on
127.0.0.1 only, so nothing beyond this machine can reach it; keep it that way until
the steps below are done.
Deploying for real
Section titled “Deploying for real”1. Create the secrets. Nothing ships with a default and nothing is generated for you: an empty value means that protection is off. Make every password you create long and random:
openssl rand -base64 32# orpython3 -c "import secrets; print(secrets.token_urlsafe(32))"| Secret | Who makes it | Needed |
|---|---|---|
AUTH_ADMIN_PASSWORD |
You: generate it | Yes. Without it the editor and the API are open to anyone who can reach the port |
WEBHOOK_SECRET |
Jambonz: copy it from the portal (account page) or GET /Accounts/{Sid}/WebhookSecret. Don’t invent one |
Yes, unless you use webhook basic auth instead |
WEBHOOK_BASIC_AUTH_PASSWORD |
You: generate it, then enter the same value on both of the application’s webhooks in Jambonz | Optional: instead of, or as well as, WEBHOOK_SECRET |
AUTH_READONLY_PASSWORD |
You: generate it | Only if you want the view-only account |
GRAFANA_ADMIN_PASSWORD |
You: generate it | Yes, with the monitoring stack on (step 7). Grafana won’t start without it |
| Session signing key | The app: written to .sesskey (mode 0600) on the store volume at first start |
Nothing to do. Deleting it signs everyone out. Anyone holding it can forge a sign-in, so treat store backups as secrets |
Both generators print no $, which Docker Compose would try to expand. A password you
pick yourself that contains $ must be single-quoted in .env. Anything under 16
characters gets a warning in the log at startup.
To change a password later, change it in .env and run docker compose up -d:
every session signed in with the old one ends on its next request. (Rotating the
webhook secret takes a little more care; see OPERATIONS.md.)
2. Write .env next to docker-compose.yml, and keep it private (it is already
gitignored and kept out of the image). Compose passes the whole file to the container
(env_file), so every setting in .env.example works there, except
STORE_DIR, DEBUG, UVICORN_WORKERS, APP_HOST and APP_PORT, which the compose
file pins:
cp .env.example .envchmod 600 .envThen fill in at least:
BASE_WEBHOOK_URL=https://ivr.example.comWEBHOOK_SECRET=<copied from the Jambonz portal>AUTH_ADMIN_USER=adminAUTH_ADMIN_PASSWORD=<generated>FORWARDED_ALLOW_IPS=<the proxy's address, as the container sees it>GRAFANA_ADMIN_PASSWORD=<generated>.env.example already turns the monitoring stack on (COMPOSE_PROFILES=monitoring,
LOG_FORMAT=json, LOG_RETENTION=30d); see step 7. For a reverse proxy on this host,
start FORWARDED_ALLOW_IPS with Docker’s private range, 172.16.0.0/12; step 3 says
why, and how to narrow it once the container is running. Every setting is described in
CONFIGURATION.md.
3. Put TLS in front. The app speaks plain HTTP on 127.0.0.1:5001 (set
APP_PUBLISH=5001 to publish it on every interface instead). Terminate HTTPS at a
reverse proxy on the same host (OPERATIONS.md has Caddy
and nginx examples) that passes Host through, sets X-Forwarded-For /
X-Forwarded-Proto, upgrades websockets for /ws/ (the editor’s Debug pane), allows
bodies up to MAX_REQUEST_BYTES and waits longer than MAX_HOOK_SECONDS for an answer.
Then set FORWARDED_ALLOW_IPS to the proxy’s address: that is how the app sees the real
client IP (the request rate limit and the failed sign-in limit both count per IP;
without it, everyone shares the proxy’s count) and that the original request was
https. Its default, 127.0.0.1, never matches in Docker: a proxy on the host reaches
the container from the compose network’s gateway, a 172.x.0.1 address that exists
only once step 4’s docker compose up has created the network. Until then, trust
Docker’s private range, 172.16.0.0/12 (add 192.168.0.0/16 if Docker has run out of
172.x networks): with the port published on loopback, nothing outside this host connects
from it. To narrow it to the gateway after step 4,
which address to trust shows how to read it; put
it in .env and run docker compose up -d again.
Not *: it makes uvicorn believe the left-most X-Forwarded-For entry, and behind
a proxy that appends to the header (nginx’s usual $proxy_add_x_forwarded_for) that
entry is whatever the client sent: every request picks its own address, past the rate
limit and the sign-in lockout, and into the log. Have the proxy overwrite the header
with the address it saw, as both examples in
OPERATIONS.md do. With an https://
BASE_WEBHOOK_URL the sign-in cookie is marked Secure automatically; set
SESSION_COOKIE_SECURE to override that either way.
4. Build it from a release tag, start it, and check the log:
git checkout v1.5.0 # the latest release; `git tag` lists themdocker compose build --build-arg APP_REVISION="$(git rev-parse HEAD)"docker compose up -ddocker compose logs app | grep -E "SECURITY|CONFIG|Editor login|Webhook basic auth"The image is named for the release (jamhooks:1.5.0) and stays on the host
when you build the next one, which is what makes a rollback quick
(upgrade and rollback). The --build-arg
records the commit in it. The container runs with a read-only root filesystem: the
store volume is the only place it writes.
You want an Editor login enabled line and no SECURITY: or CONFIG: line. After
any later change to .env, run docker compose up -d again: it recreates the container
with the new values (docker compose restart keeps the old ones).
5. Point Jambonz at it. An application has two webhooks; set both (method POST):
the calling webhook https://ivr.example.com/webhooks/<flow name>, and the call
status webhook …/webhooks/<flow name>/callstatus; without the second, the flow’s
Call Status and Disconnect handlers never run. The flow’s detail page lists both. With
WEBHOOK_SECRET set there is nothing else to enter; if you use webhook basic auth
instead, enter the same username and password on both.
6. Back up the store volume. Flows, version history and the session key all live in
the storedata volume (/app/data in the container). There is no database to dump:
scripts/backup.sh stops the app, copies the volume and starts it again, and
scripts/restore.sh puts an archive back;
OPERATIONS.md has the details and a cron line. A
backup contains the session-signing key, so keep it as private as .env.
7. Monitoring and alerts. With the .env from step 2, docker compose up -d also
starts the monitoring stack: Loki keeps the app’s logs for LOG_RETENTION (30 days
by default) and then deletes them, Alloy collects them and probes /health, and Grafana
(on 127.0.0.1:3000, through an SSH tunnel or the proxy) has a dashboard and alert
rules for an unreachable app, shed or failing webhooks, slow webhooks, an unwritable
store, password guessing, an unsafe configuration and any other error. Two things to do
once it runs:
GRAFANA_PASSWORD='<GRAFANA_ADMIN_PASSWORD>' python3 scripts/check_monitoring.py --wait 180checks it is collecting and alerting; then, in Grafana, Alerting → Contact points
decides where alerts go (email, Teams, Slack, a webhook); until then they reach no one.
Add an outside uptime check on https://<your host>/health for the host itself going
down. Don’t restart the app on a 503 from /health: calls keep being answered, a
restart drops every one in progress and fixes none of the causes
(health and logs).
Monitoring has the details, what each alert means and how to
run without the stack (remove the COMPOSE_PROFILES line).
Once running, a sign-in ends after SESSION_IDLE_TIMEOUT seconds without a request
(default one hour), and an address that fails LOGIN_MAX_ATTEMPTS sign-ins within
LOGIN_LOCKOUT_SECONDS is locked out for that long. If failures from many addresses add
up to LOGIN_GLOBAL_MAX_ATTEMPTS, sign-in pauses for browsers that have never signed in
here, and the log says so at ERROR (worth an alert). What else the app defends against
is in HARDENING.md.
Without Compose
Section titled “Without Compose”The same image runs with plain docker run. Pass it the same .env:
docker build -t jamhooks:1.5.0 \ --build-arg APP_VERSION=1.5.0 --build-arg APP_REVISION="$(git rev-parse HEAD)" .docker run -d --name ivr --restart unless-stopped --stop-timeout 45 \ --read-only --tmpfs /tmp:size=64m \ --log-opt max-size=10m --log-opt max-file=5 \ -p 127.0.0.1:5001:5001 --env-file .env -v ivr-store:/app/data jamhooks:1.5.0--env-file takes each line literally: no quotes, no ${…}, and no comment after a
value. --stop-timeout 45 gives uvicorn time to drain: on SIGTERM it waits up to
GRACEFUL_SHUTDOWN_SECONDS (40) for running requests (well past MAX_HOOK_SECONDS, the
longest a webhook can run, so a webhook in flight still answers), and Docker’s own
default of 10 s would kill it first. Leave STORE_DIR, DEBUG, UVICORN_WORKERS,
APP_HOST and APP_PORT at the image’s defaults (the values the compose file pins) or
match the -p and -v flags to what you set.
The --log-opts bound the log the way the compose file does; without them Docker’s
default driver keeps everything, forever, unless the daemon sets a limit. The backup
scripts drive the compose file; with plain docker run, do what
scripts/backup.sh does: stop the container, read the volume as
root (its files are owner-only), start it again whether or not the copy worked.
Instead of the login accounts, editor auth can be delegated to a gateway with
TRUSTED_USER_HEADER (see HARDENING.md). Set LOG_FORMAT=json if you
aggregate logs. DEBUG is already false in the image.
One instance per store
Section titled “One instance per store”Keep UVICORN_WORKERS=1 and run one instance of the app per store (the default). A
second process pointed at the same store fails to start (it can’t take the advisory lock
on <store>/.lock) rather than corrupting the uniqueness and version invariants. There
is no read-only or webhook-only instance mode, and a copy of the store is not a
replica: an instance on a copy has its own writable editor, and the two diverge from the
first save. Under an orchestrator that means replicas: 1 with a stop-before-start
rollout (Kubernetes strategy: Recreate), on a local or block volume; flock on NFS,
CIFS and some FUSE mounts may not be enforced across machines. High availability is a
job for the future hosting platform; see
OPERATIONS.md.