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-orphans

tinyserver-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-orphans

TINYSERVER_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.txt

A 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

CommandEffect
statusThe mode, the notice, since when, and whether there is a hold
suspend --read-only --notice TEXTReading, 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 TEXTOnly the health and status routes answer. Open connections close within a minute.
resumeNormal again. The notice is cleared.
hold --reason TEXT, releaseA 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.

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.

VariableDefaultMeaning
TINYSERVER_PUBLIC_IPunsetThe IPv4 address members reach the media port at. Unset, calls have no media.
TINYSERVER_MEDIA_PORT50000The one port for call audio and video, UDP and TCP
TINYSERVER_LAN_IPunsetThe host’s address on the home network, for members on it
TINYSERVER_MEDIA_EGRESS_KBPSno budgetWhat the host can upload for calls, in kb/s
TINYSERVER_CALL_ROOM_MAX, TINYSERVER_CALL_SERVER_MAX12, 32People in one room’s call, and in calls on the whole server
TINYSERVER_SESSION_MAX_DAYS30Days a sign-in lasts, 1 to 365. Nothing extends a session.
TINYSERVER_PASSKEY_RP_NAMETinyCommsThe name a browser shows when it asks for a passkey
TINYSERVER_PASSKEY_RP_IDthe host of the public URLThe 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_HEADERprivate and loopback peers; Cloudflare’s headerWhose client-address header the sign-in limiter believes, and which header
TINYSERVER_LOG_LEVELinfoHow much the log says
TINYSERVER_LOG_RING, TINYSERVER_LOG_EXPORTon, onWhether a debug ring is kept, and whether SIGUSR1 may write it to disk
TINYSERVER_REPORT_RETENTION_DAYS90Days a resolved abuse report is kept, 7 to 3650
TINYSERVER_PG_DIR, POCKETID_DATA_DIRDocker volumesHost directories for the data
TINYSERVER_MEM_LIMIT, TINYSERVER_PIDS_LIMIT, TINYSERVER_CPUS1g, 512, 2Caps on the server container
TINYSERVER_PG_MEM_LIMIT, TINYSERVER_PG_PIDS_LIMIT1g, 256Caps on Postgres
TINYSERVER_CLAMD_MEM_LIMIT3gCap on the scanner
TINYSERVER_IMAGEbuilt on the hostWith compose.image.yml: the published image to run
TINYSERVER_INSIDE_SUBNET, TINYSERVER_TUNNEL_IP172.30.53.0/24, 172.30.53.10The 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 -d

This 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 -d

deploy/tenant/README.md has the rest.

Edit this page on GitHub