Host it for your team

Two commands put the production image on a server. Read the whole page before the last one, because the default binding is deliberately local-only.

1. Set a database password.

   echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" >> .env

   Compose refuses to start without it — ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}.

2. Start it.

   docker compose -f docker-compose.prod.yml up -d

   This pulls jaklimoff/ushabti, applies the migrations at start and serves on 127.0.0.1:3000 — bound to loopback, so nothing reaches it until you put a proxy in front.

3. Put TLS in front of it. In production the session cookie is marked secure, so a browser will not send it back over plain http. Without a proxy, nobody can stay signed in.

4. Close sign-up once your team has registered.

   echo "USHABTI_SIGNUP=closed" >> .env
   docker compose -f docker-compose.prod.yml up -d

5. Optional: let the server email invites and reset links. Give it an SMTP server and a sender:

   echo "SMTP_URL=smtps://user:password@smtp.example.com:465" >> .env
   echo 'MAIL_FROM="Ushabti <board@example.com>"' >> .env
   docker compose -f docker-compose.prod.yml up -d

   Without them nothing is emailed, and the owner sends the link by hand. See SMTP_URL and MAIL_FROM.

   Add the board’s public address as well, and the sign-in page offers Forgot password?, so a person can get a reset link by email without asking anybody:

   echo "USHABTI_URL=https://tasks.example.com" >> .env
   docker compose -f docker-compose.prod.yml up -d

   The emailed link is built from this address and never from the request. See USHABTI_URL.

A webhook cannot reach inside your network by default

A webhook is the one request a person tells the server to make for them, so Ushabti refuses a loopback, private or link-local address: 169.254.169.254 is a cloud’s metadata service, 127.0.0.1:5432 says whether a database is listening, and 10.0.0.5 is whatever your neighbour is running. The check runs when the URL is saved and again before every try, resolving the name each time, so a public name that starts pointing inside is refused then.

If your receiver really is on that network — an internal CI runner, a service on the same compose network — set USHABTI_WEBHOOK_PRIVATE=1:

echo "USHABTI_WEBHOOK_PRIVATE=1" >> .env
docker compose -f docker-compose.prod.yml up -d

Only the owner or an admin of a project can make a webhook at all, and an agent token is refused by every one of its routes. This flag decides how far a webhook may reach once one exists.

What the rate limit does, and what it does not

Ushabti counts ten failures in ten minutes and then answers 429 with a Retry-After header, for a wrong password by address and by email, for a refused sign-up by address, for a bad agent token by address, and for a dead reset link by address. A sign-in that works counts nothing and clears the count for that email, so nobody is locked out by their own team.

One address is often many people. Behind one NAT — an office, a VPN, a school — everybody shares the address, so ten failures from one desk answer 429 to all of them for ten minutes, on sign-in, sign-up, agent tokens and reset links alike. A sign-in that works clears the count for that email and not for the address.

The count lives in the memory of one process. Restarting the container forgets it, and two Ushabti processes behind one address would each count to ten. This is enough for the single server the image is built for; it is not a defence against a botnet. A proxy that limits requests is worth having in front of it.

The address is the first value of x-forwarded-for, which is your proxy’s job to write. Have it replace the header rather than add to it — proxy_set_header X-Forwarded-For $remote_addr; in nginx — or a caller can name any address it likes and get a fresh ten tries each time.

Have it replace X-Forwarded-Host as well — proxy_set_header X-Forwarded-Host $host;. That header is where a reset link and an invite get the address they carry, so a caller that names the host writes the address the owner copies out of the page — or the one the server emails — and sends to a colleague. The token in it is real, which is what makes it worth writing.

Which image, which tag

The same image is published to Docker Hub and to ghcr.io/jaklimoff/ushabti, built from the same commit by the same workflow. Pick either.

Tag	What it is	Use it for
:edge	main, rebuilt each night	Trying things. Not production.
0.5.0	A release	Production. Pin it.

Pin a release by setting USHABTI_VERSION in .env:

USHABTI_VERSION=0.5.0

Add --build to the compose command to build the image from your own checkout instead of pulling.

Upgrading

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

The container’s command is node scripts/migrate.mjs && node server.js, so every start applies any migration the database has not seen. There is no separate migration step to remember.

Check the changelog before a jump: some releases carry a note. The 0.3.0 upgrade, for example, closes any open run whose agent last reported over thirty minutes ago the first time somebody loads the board.

Checking it is up

GET /api/health answers 200 while the app can reach its database and 503 when it cannot. It needs no session and no token, and the answer is only {"ok":true}, so point Uptime Kuma, a load balancer or a Kubernetes probe at it:

curl -fsS http://127.0.0.1:3000/api/health

The app service in docker-compose.prod.yml has a healthcheck that asks it, so docker compose -f docker-compose.prod.yml ps shows the app as healthy or unhealthy.

A database you already have

Point DATABASE_URL at it and drop the db service. Two things about managed clusters:

TLS

node-postgres verifies the certificate when the URL says sslmode=require. That is stricter than libpq and than most other drivers, so a URL that works elsewhere can fail here. Give it the provider’s CA:

DATABASE_URL="postgres://user:pass@host:5432/ushabti?sslmode=verify-full&sslrootcert=/etc/ssl/ca.crt"

Connection count

DATABASE_POOL_MAX=6

One Ushabti process otherwise holds up to twelve connections, and takes one more per open browser tab for live updates — every SSE stream keeps a LISTEN connection outside the pool. DigitalOcean’s smallest managed cluster allows 25 connections for everything.

What the image is

A three-stage node:24-bookworm-slim build using Next’s output: "standalone", so the runner installs nothing at start.

If you fork it

The standalone output carries only the files the build saw the server touch. Nothing imports scripts/migrate.mjs, so its packages are named by hand in outputFileTracingIncludes in next.config.mjs, next to drizzle/** and examples/skill/ushabti/**. Add an import to that script without adding it there and the image builds, starts, and dies on the first line.

Backing it up

The board is in Postgres. The files people attach to a task are not: they live in the S3 bucket named by S3_BUCKET, and the database holds only their names and keys. A dump alone brings back every task with its files missing, so back up both.

The database:

docker compose -f docker-compose.prod.yml exec db \
  pg_dump -U ushabti ushabti | gzip > ushabti-$(date +%F).sql.gz

The bucket, if you set one. Copy it to a second bucket or a disk, with any S3 tool. Take it after the dump, so every file the dump names is already there:

aws s3 sync s3://ushabti-files ./ushabti-files-$(date +%F) --endpoint-url "$S3_ENDPOINT"

Versioning on the bucket, where your provider has it, also keeps a file somebody removed.

A task you archive keeps everything and can be put back. A deleted task can be put back for 30 days, from Deleted, gone in 30 days. After that it is gone, and the backup is the only way back.

A backup nobody has restored is a guess, so try one into an empty database before you need it:

docker compose -f docker-compose.prod.yml exec db createdb -U ushabti ushabti_restore
gunzip -c ushabti-2026-09-20.sql.gz | docker compose -f docker-compose.prod.yml exec -T db \
  psql -U ushabti -d ushabti_restore -v ON_ERROR_STOP=1 -q

Then count what came back — select count(*) from tasks — against the live database, and drop the scratch one.

The Export row on Settings → Project is not this. It saves one project as a JSON file an owner or an admin can read and take away, without shell access. It leaves out the activity feed, the runs and every account’s password, so it cannot bring an instance back. pg_dump stays the backup of the whole instance.

ConfigurationEvery environment variable, what it does and what it defaults to.