Operate and upgrade
Upgrades, backups, suspension, logs, and every optional setting.
Commands run from deploy/, next to compose.yml and .env.
Upgrade
Back up the database first, then pull and rebuild:
docker compose exec -T postgres pg_dump -U postgres tinyserver > backups/before-upgrade.sql
git pull
docker compose up -d --build --remove-orphanstinyserver-init applies any new migrations and exits before the server starts. If it fails, the server does not start; docker compose logs tinyserver-init says why.
Going back to an older release means restoring that backup: an older binary refuses a database that has migrations it does not know.
Some releases need a step from you, such as the one that moved the sign-in choice into the app. Upgrading in deploy/README.md lists them. Read it before each upgrade.
Running a published image
Every push to main that passes CI is published as ghcr.io/tinycomms/tinyserver:<sha> and :main. compose.image.yml runs that image instead of building one on the host. Name the sha, not :main, so the host runs the commit you chose and going back is naming the one before.
docker compose exec -T postgres pg_dump -U postgres tinyserver > backups/before-upgrade.sql
TINYSERVER_IMAGE=ghcr.io/tinycomms/tinyserver:<sha> \
docker compose -f compose.yml -f compose.image.yml up -d --pull always --remove-orphansTINYSERVER_IMAGE can live in the environment file instead. The binary carries its migrations; the checkout is still where the compose files and the Postgres init script come from.
Stop
docker stop sends SIGTERM. The server ends every call, finishes the requests it has, and exits. Calls live in memory, so a restart ends them.
Back up, restore and move
tenant/operator.sh works on a single community when given --stack .env. Backups are encrypted with age, which has to be on the host.
sh tenant/operator.sh backup --stack .env --out community-2026-11-01.age --recipient age1...
sh tenant/operator.sh restore --stack .env --in community-2026-11-01.age --identity operator.key
sh tenant/operator.sh export --stack .env --out community-export.age --recipients-file owner.txtA backup holds the database, the uploads, Pocket ID’s data, the secrets, and the server’s end-to-end key file. That key is not in the database, so a plain pg_dump does not contain it. Losing the key file and its database row together stops the server from starting, rather than making a key that members’ apps would reject.
export writes the same to hand to someone who will run the community elsewhere. delete removes it and asks for the name again with --confirm.
Suspend and hold
| Command | Effect |
|---|---|
status | The mode, the notice, since when, and whether there is a hold |
suspend --read-only --notice TEXT | Reading, signing in and out, deleting your account and filing a report still work. Every other write is refused. Calls already running go on until they end; new ones are refused. |
suspend --offline --notice TEXT | Only the health and status routes answer. Open connections close within a minute. |
resume | Normal again. The notice is cleared. |
hold --reason TEXT, release | A legal hold. Resolved reports stop expiring, and operator.sh refuses to delete or overwrite the community. |
Members see the notice, 1 to 500 characters. The public status route never says whether there is a hold.
Logs
The server logs on its own machine only. There is no exporter and no telemetry.
- The log is stderr; Docker keeps three files of 10 MB. The level is
infounlessTINYSERVER_LOG_LEVELsayserror,warn,debugortrace.RUST_LOGis ignored. - A debug ring of about 2,000 lines, none older than an hour, stays in memory. It is written to disk only when the process receives
SIGUSR1, and bundles older than 24 hours are deleted on the next start. - Message text, filenames, tokens, keys, invite secrets, email addresses, display names, and call setup (SDP) are never recorded. Ids such as
user_id,room_idandcall_idare. - Client addresses are kept out of the log unless
TINYSERVER_LOG_PEER_IP=on, and then only on the debug ring.
During a call the log has a media counters line once a minute. Calls and media says how to read it.
Housekeeping
Every ten minutes the server deletes expired sessions, expired invites nobody used, sign-ins nobody finished, one-time codes nobody redeemed, uploads never attached to a message after an hour, and resolved reports past their retention. Accepted invites stay in the invite list.
Optional settings
Unset, each has the default the compose file gives it. They go in deploy/.env.
| Variable | Default | Meaning |
|---|---|---|
TINYSERVER_PUBLIC_IP | unset | The IPv4 address members reach the media port at. Unset, calls have no media. |
TINYSERVER_MEDIA_PORT | 50000 | The one port for call audio and video, UDP and TCP |
TINYSERVER_LAN_IP | unset | The host’s address on the home network, for members on it |
TINYSERVER_MEDIA_EGRESS_KBPS | no budget | What the host can upload for calls, in kb/s |
TINYSERVER_CALL_ROOM_MAX, TINYSERVER_CALL_SERVER_MAX | 12, 32 | People in one room’s call, and in calls on the whole server |
TINYSERVER_SESSION_MAX_DAYS | 30 | Days a sign-in lasts, 1 to 365. Nothing extends a session. |
TINYSERVER_PASSKEY_RP_NAME | TinyComms | The name a browser shows when it asks for a passkey |
TINYSERVER_PASSKEY_RP_ID | the host of the public URL | The domain passkeys belong to. Set it before anyone makes one, or not at all. |
TINYSERVER_OIDC_* | A sign-in provider. Sign-in and passkeys lists them. | |
TINYSERVER_TRUSTED_PROXIES, TINYSERVER_CLIENT_IP_HEADER | private and loopback peers; Cloudflare’s header | Whose client-address header the sign-in limiter believes, and which header |
TINYSERVER_LOG_LEVEL | info | How much the log says |
TINYSERVER_LOG_RING, TINYSERVER_LOG_EXPORT | on, on | Whether a debug ring is kept, and whether SIGUSR1 may write it to disk |
TINYSERVER_REPORT_RETENTION_DAYS | 90 | Days a resolved abuse report is kept, 7 to 3650 |
TINYSERVER_PG_DIR, POCKETID_DATA_DIR | Docker volumes | Host directories for the data |
TINYSERVER_MEM_LIMIT, TINYSERVER_PIDS_LIMIT, TINYSERVER_CPUS | 1g, 512, 2 | Caps on the server container |
TINYSERVER_PG_MEM_LIMIT, TINYSERVER_PG_PIDS_LIMIT | 1g, 256 | Caps on Postgres |
TINYSERVER_CLAMD_MEM_LIMIT | 3g | Cap on the scanner |
TINYSERVER_IMAGE | built on the host | With compose.image.yml: the published image to run |
TINYSERVER_INSIDE_SUBNET, TINYSERVER_TUNNEL_IP | 172.30.53.0/24, 172.30.53.10 | The internal network and the tunnel’s address on it. Change both if the range is taken. |
Scanning off
docker compose -f compose.yml -f scan-off.yml up -dThis runs without clamd and marks every upload clean without scanning it. It is only for a community whose attachments are sealed on the sending device, where the server could scan nothing but ciphertext. Anywhere else it lets any file through.
Many communities on one host
tenant/tenant.sh runs the same compose file once per community, each with its own project, networks, volumes, subnet, media port, database, roles, passwords and secrets.
sh tenant/tenant.sh new acme --chat-url https://acme.example.org \
--auth-url https://auth.acme.example.org --tunnel-token <token>
sh tenant/tenant.sh compose acme up -ddeploy/tenant/README.md has the rest.