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
- A Linux server you control: 1 vCPU and 1 GB of memory are enough.
- Docker with the Compose plugin.
- A domain name, with an A or AAAA record pointing at the server. Turn off any CDN proxy: the server needs the real connections, and a proxy would see every member’s address.
- Ports 80 and 443 open. Nothing else needs to be.
Set it up
The Compose file runs the server behind Caddy, which gets and renews its HTTPS certificate, plus a nightly backup.
-
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 -
Name the image and your domain in
.env. The service is calledrelay-testnetfor 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 -
Start it and check it answers:
sudo docker compose up -d curl https://relay.example.org/health # ok - 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.
-
Put a token in
secrets.env, next tocompose.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 - 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. - Members’ phones keep the token with the vault and in backups, since restoring the vault needs it. If it leaks, change it in
secrets.envand give the group the new one.
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=offturns 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=offturns 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=offkeeps everything.
Messages waiting for a member are deleted once picked up, and after 30 days in any case.
Good to know
- No notifications: they need Zafe’s notification key, so only Zafe’s servers send them. Phones check in the background and when Zafe opens.
- Every member must reach it over HTTPS, with a certificate phones trust. Members who use Tor can’t reach a private network address.
- You see what any server sees: who talks to which vault, when, and from which IP address. The Caddy setup keeps no access log; keep it that way.
- Run one instance per database file. Never two containers on the same data, and no scaling out.
- Want it in the app’s server list? Open a pull request adding it to
relay_presets.dart, with your name as its operator. - Own reverse proxy instead of Caddy? Let responses take 40 seconds or more (the app holds requests open for 25), and set
ZAFE_RELAY_CLIENT_IP_HEADERto a header your proxy overwrites.
If it goes wrong
- The app says “Not a Zafe server.” or “Couldn’t connect.”
- Open
https://relay.example.org/healthin a browser: it should sayok. If the certificate fails, check that DNS points straight at the server, thensudo 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