Skip to content

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.

docker-compose.yml runs the single app service and persists the JSON store in a named volume:

Terminal window
docker compose up --build # http://127.0.0.1:5001

Without 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.

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:

Terminal window
openssl rand -base64 32
# or
python3 -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:

Terminal window
cp .env.example .env
chmod 600 .env

Then fill in at least:

BASE_WEBHOOK_URL=https://ivr.example.com
WEBHOOK_SECRET=<copied from the Jambonz portal>
AUTH_ADMIN_USER=admin
AUTH_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:

Terminal window
git checkout v1.5.0 # the latest release; `git tag` lists them
docker compose build --build-arg APP_REVISION="$(git rev-parse HEAD)"
docker compose up -d
docker 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:

Terminal window
GRAFANA_PASSWORD='<GRAFANA_ADMIN_PASSWORD>' python3 scripts/check_monitoring.py --wait 180

checks 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.

The same image runs with plain docker run. Pass it the same .env:

Terminal window
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.

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.