Run your own server

One Docker container and one SQLite file, behind HTTPS on your domain.

Most groups can use Zafe’s server. Run your own if you’d rather no outside operator sees when your members talk, want to look after its uptime yourself, or want to offer one to other groups. It holds no keys and can’t spend.

Before you start

Set it up

The Compose file runs the server behind Caddy, which gets and renews its HTTPS certificate, plus a nightly backup.

  1. Get the files:
    git clone --depth 1 https://github.com/zafe-cash/zafe
    sudo cp -r zafe/infra/relay/vps /opt/zafe-relay
    cd /opt/zafe-relay
  2. Name the image and your domain in .env. The service is called relay-testnet for historical reasons; it serves mainnet vaults too.
    sudo tee .env <<'EOF'
    RELAY_TESTNET_IMAGE=ghcr.io/zafe-cash/zafe-relay:main
    RELAY_TESTNET_DOMAIN=relay.example.org
    EOF
    sudo install -d -o 10001 -g 10001 -m 700 /var/backups/zafe-relay/testnet
  3. Start it and check it answers:
    sudo docker compose up -d
    curl https://relay.example.org/health      # ok
  4. Check it from a phone: on New vault, tap More options, Server, then Other address, and enter relay.example.org. Use this server turns on once it answers.

Make it private

By default anyone can create a vault on your server. With a create token, creating or restoring a vault needs it; joining, paying and everything else doesn’t.

  1. Put a token in secrets.env, next to compose.yml, and restart:
    echo "ZAFE_RELAY_CREATE_TOKEN=$(openssl rand -hex 24)" | sudo tee secrets.env > /dev/null
    sudo chmod 600 secrets.env
    sudo docker compose up -d
  2. Give the group the address and token in one piece: relay.example.org#<token>. Pasted or scanned into Other address, it fills in the Create token.
  3. Members’ phones keep the token with the vault and in backups, since restoring the vault needs it. If it leaks, change it in secrets.env and give the group the new one.
Zafe's server list: relay.zafe.cash run by Zafe, and Other address set to relay.dao.org, with the line “No notifications” and an empty Create token field.
A private server in the app’s server list.

Back it up

A backup runs every night at 03:17 UTC into /var/backups/zafe-relay/testnet, kept 14 days, plus the newest 2 taken before updates. Copy that folder off the machine too. Take one by hand with:

sudo docker compose exec backup-testnet sh /backup.sh once

A lost or old database doesn’t lose funds or vaults: every phone keeps the history, and a member taps Restore vault on the server on the Status screen. Restore the newest backup anyway; the steps are in the relay README.

Update it

sudo docker compose exec backup-testnet sh /backup.sh once
sudo docker compose pull && sudo docker compose up -d

main is the image Zafe’s test server runs after every change. To choose when you update, use a sha-<commit> tag instead. An outdated server shows in the app as “Needs an update”. To check where an image came from:

gh attestation verify oci://ghcr.io/zafe-cash/zafe-relay:main -R zafe-cash/zafe

Defaults

Add any of these to secrets.env to change them; 0 turns one off.

ZAFE_RELAY_KEY_RATE · ZAFE_RELAY_IP_RATE
Requests per minute: 300 per member key, 1,200 per IP address. Over them the server answers “busy”. ZAFE_RELAY_LIMITS=off turns all rate limits off.
ZAFE_RELAY_CREATES_PER_DAY · ZAFE_RELAY_MAX_VAULTS_PER_KEY
New vaults: 20 a day per IP address, 8 per key.
ZAFE_RELAY_MAX_INBOX · ZAFE_RELAY_MAX_DELIVERY_MB · ZAFE_RELAY_MAX_LOG_MB
Per vault: 256 waiting messages and 2 MiB from each member to each other member, 64 MiB of waiting messages, 512 MiB of history (at most half from one member), so one member can't fill an inbox or the vault for everyone. History is kept for good, so 512 MiB is about seven years of 10 payments a day. ZAFE_RELAY_QUOTAS=off turns these off.
ZAFE_RELAY_MAX_DB_MB
The whole server's storage, in MiB (off unless set; size it to your disk). Past it writes are refused. At 90% new vaults stop, and so do writes from vaults that came to this server in the last 30 days.
ZAFE_RELAY_IDLE_DAYS · ZAFE_RELAY_UNUSED_DAYS
A vault is deleted after 365 days with no member request, or 30 days after it was created if no member but its creator ever connected. ZAFE_RELAY_EXPIRY=off keeps everything.

Messages waiting for a member are deleted once picked up, and after 30 days in any case.

Good to know

If it goes wrong

The app says “Not a Zafe server.” or “Couldn’t connect.”
Open https://relay.example.org/health in a browser: it should say ok. If the certificate fails, check that DNS points straight at the server, then sudo docker compose logs caddy.
“It runs an older Zafe server and can’t hold new vaults.”
Pull the newest image (above).
“This server is private: it needs its create token.”
Send the member relay.example.org#<token>.

Checked with Zafe 0.1.23 · 2026-10-27