Administration ​
Most of running an instance happens in the app, under Manage instance, for accounts with the instance ADMIN role. A few jobs are command-line tasks.
In the app ​
- Users and Approval: manage accounts. With
adminApprovalRequiredin app.config.yaml, every new account waits under Approval. - Emoji and Badges: the instance's custom emoji packs and profile badges.
- Activities: install packaged activities and add ones hosted elsewhere (see Activities).
- IP Bans: block addresses from the instance.
- Config: instance details and features (including the file size limit), rate limits, streaming limits and the mobile push relay.
- Stats for nerds: charts of activity, connections, latency, CPU and memory over time, plus the instance's current inventory.
Stats for nerds ​
The collector samples each server process every minute and keeps history for a configurable 1 to 365 days. It stores aggregate counts only: no IP addresses, message contents, URLs or user IDs. Regions are broad time-zone groups reported by clients, not locations. Collection settings turns each category on or off for the whole instance, and Customise dashboard changes only your own view.
History starts when the collector first runs, so a new instance needs a few minutes before charts appear. CPU and memory describe the host the server runs on, not a container quota or a separate database or LiveKit host.
Rate limits ​
Under Config → Message and media rate limits, each limit is requests per minute, and 0 means unlimited:
| Setting | Default | Counts |
|---|---|---|
| Messages per minute | 30 | New messages, forwards and polls, per account |
| Message actions per minute | 120 | Reactions, edits, deletes, pins, votes, history, search, read state and uploads, per account |
| Media requests per minute | 0 (unlimited) | Views and downloads of media: public media per IP address, attachments per account |
Changes apply immediately across every server process.
Commands ​
Run these in a one-off container from the docker/ directory, as docker compose run --rm backend yarn cli <command>:
| Command | What it does |
|---|---|
--create-admin <email> <password> | Creates an admin account. The first one is needed before the server will start |
--import-emoji <path> [morePaths...] [--user=<id>] [--dry-run] | Imports a custom emoji pack from a .zip or a folder of images. 5450-pepe-dab.png becomes :pepe-dab:. Owned by the first admin unless --user |
--prune-media [--apply] | Finds removed or abandoned uploads, and local files no upload refers to. Only reports, until you add --apply |
--reindex-search | Rebuilds the message search index from the database. Safe at any time |
--federation-trust <domain> approve|reject|accept-key|reject-key [--discard-held] | Decides on another instance waiting for approval, or one signing with a new key, as Manage instance → Federation does (see Federation) |
--prune-federation | Removes copies of other instances' servers, conversations and people that nothing uses any more. The server also does this daily |
Paths given to --import-emoji are inside the container, so mount the pack in first, or copy it into docker/data/refract/ and use /data/....
Two more run through yarn directly: docker compose run --rm backend yarn migrate applies database migrations (see Upgrading), and yarn seed fills a test instance with demo data.
Sign-ins and sessions ​
- A web sign-in lasts 30 days. The mobile app keeps a persistent sign-in until it's signed out or revoked.
- Changing or resetting a password, changing an email address, or denying an account signs that account out everywhere at once: its connections are closed, and its calls are ended.
- People can see their signed-in phones and sign one out remotely, for example a lost phone. That also stops its push notifications.
- Keep server clocks in sync: sign-in tokens expire by the clock.