Self-hosting
Admin panel
Every instance setting, moderation queue, and security switch — all at /admin, no config files.
Sign in as an admin or a moderator and open /admin. Everything the setup
wizard set — and more — is editable here, subject to your role.
Instance
- Name and public domain.
- The federation toggle.
- The signed-out visitor card (tagline and banner image).
- Public information — About, rules, privacy policy, and operator contact and status links.
- Session-secret rotation.
- Optional Umami Cloud website statistics, disabled by default.
Domain and federation changes apply on the next restart; the page tells you when a restart is needed. Everything else on this tab applies immediately.
Visitor card
The card shown to signed-out visitors. Leave the tagline blank to use the built-in sentence, and upload a banner image or revert to the bundled artwork. Images are resized and re-encoded automatically.
Public information
The instance-specific pages linked from the footer — About, instance rules, privacy, contact, and status — are edited here, by admins only. The three page sections accept Markdown and are rendered to sanitized HTML server-side:
- About this instance appears on
/aboutunder “This instance”. - Instance rules appears on
/aboutunder “Instance rules”. - Privacy policy replaces the placeholder notice on
/privacy. If Umami Cloud is enabled, its disclosure is shown alongside your policy.
Leave any of them blank to keep the built-in placeholder text. Placeholders are safe defaults, not legal advice: replace the privacy text with your own policy before operating a public service.
Contact and status fields may each be left blank:
- Contact email and abuse email are shown on
/contact. The abuse address falls back to the contact email when unset. - Contact page URL replaces the footer’s Contact link when set.
- Status page URL replaces the footer’s Status link when set.
When an instance value is unset, the corresponding PUBLIC_* environment
fallback applies if configured — see
Environment variables. Instance
settings take precedence over the environment.
Rotating the session secret
Rotate the secret that signs login sessions only if you suspect it was exposed. It signs everyone out — including you — on the next restart, and is guarded by a confirmation dialog.
If you pinned the secret yourself via the SESSION_SECRET environment variable,
the UI tells you to rotate it there instead: an env-supplied value wins over the
generated one.
Switch modes, edit connection details, generate DKIM keys, verify DNS records, and send a live test. Passwords are write-only — the UI shows “unchanged” rather than reading a stored secret back to the browser.
Full detail: Email.
Reports
The moderation queue, shared with moderators. Review user-reported posts and actors, remove posts, and dismiss reports. Reports cover both local and remote content.
Users
Suspend or reinstate local accounts. A suspended account cannot sign in, and its content stops being served. Moderators share this tab but can only act on regular accounts — never on admins or fellow moderators.
Freeze is a reversible hold for the same accounts, from the same row. A frozen account cannot sign in, its profile shows as deactivated, and its posts, comments and lists are hidden. Remote instances are told: the account’s posts are retracted from them, and restored when it is unfrozen. Freezing a suspended account is allowed.
Deleting an account hides it everywhere but keeps it restorable for 30 days — see Moderation tools. Erasing it from Recently deleted is permanent.
Edit updates an account’s profile — display name, bio, public email, custom section, tags, links — or its login email. A login-email change needs re-verification: the new address gets a confirmation link, the old address gets a security notice, and the account stays unverified until the new address is confirmed.
Federation
Three sections:
- Federation network — the instances this one caches ahead of its readers, FediDB discovery, and the sync settings. See The federation network.
- Domain blocks — suspend a domain (full defederation, purges already-cached content) or limit it (keeps federating, hidden from Global, Trending and auto-caching).
- Account blocks — block a single remote account for the whole instance.
See Moderation tools for what each block does.
Security
AI-scraper protection
A lightweight proof-of-work challenge (Anubis) in front of the interactive half of the app. It is off by default.
When enabled, browser-like traffic to these routes is challenged — a real browser solves it in about a second, most scrapers cannot:
/composeand/search/dashboard,/drafts,/posts/manageand the post editor/settings,/admin,/notifications,/follow-requests,/lists- Sign-in, registration, and password reset
Deliberately never challenged:
- Reading — the home feed, profiles, posts, tag pages and public reading lists, for everyone, with or without JavaScript.
- Federation — ActivityPub delivery keeps working.
- The API — API clients are untouched, and so is everything a page loads for itself: more responses, further pages of a feed, every uploaded image.
- Feeds and sitemaps — RSS readers and search engines keep working.
- OpenGraph crawlers — link-preview cards still render.
- URLs that do not exist — a bad link gets a real 404, not an interstitial, so stale URLs can drop out of search indexes.
A request that does not send a browser-shaped User-Agent is never challenged either, on any route.
What a challenged request gets back
503 Service Unavailable, with Retry-After: 3600 and
<meta name="robots" content="noindex,nofollow"> on the page.
This is deliberate, and worth knowing before your monitoring tells you about it. A challenge is a temporary refusal to serve, and 503 is the code that says so: a search engine keeps the URL and comes back, a link checker does not report a dead link, and an archive does not store an interstitial as the page. Answering 200 — which is what the challenge service does by default — tells every automated client the request succeeded while handing it a page that is not the one asked for, which a search engine reads as a soft 404 and, since every challenged URL returns the same interstitial, as a set of duplicates of one another.
A denial (no rule issues one in the shipped policy) answers 403 Forbidden.
Custom IP block rules also return 403, independently of
the challenge switch.
None of this changes anything for a reader: browsers render an error page and run its scripts exactly as they would a 200, so the challenge is solved and the page loads as before.
The toggle applies live: no restart, no config file. The backend re-routes the app through the bundled challenge service via Caddy’s internal admin API. Per-IP rate limiting stays accurate.
The challenge service always runs but only sits in the request path while the
toggle is on. Its signing key is generated once into the secrets volume, so
restarts and upgrades do not re-challenge anyone who has already solved one.
Which routes are challenged is set by botPolicy.yaml at the repository root.
It is read once at startup, so an edit needs docker compose restart anubis.
What a visitor without JavaScript sees
Solving the challenge needs JavaScript, so a visitor browsing without it — off in the browser, or blocked for your domain by an extension — cannot get past the screen. Neither can one whose browser runs JavaScript perfectly well but failed to fetch the challenge script.
The challenge screen carries a footer line for both of them: what the screen is, that reading needs none of it, and a link to your home page. Beside it is an Imprint link to a longer page explaining which of the two failures a reload will fix.
Nothing they are likely to want is behind the wall. Reading is never challenged, so the link out is a real way back into the site rather than an apology.
To add your own support address to that explanation, edit the impressum.page
body in botPolicy.yaml and restart:
docker compose restart anubis
What the challenge screen looks like
The screen is drawn by the challenge service, not by Omicron — it answers before the request reaches the app — so it is not a page the admin panel can change. Left alone it arrives in that project’s own colours, which look nothing like the rest of your site.
Omicron replaces the stylesheet and mascot artwork instead. anubis-theme.css
at the repository root carries the app’s palette, typography and dark mode, and
Caddy serves it at the path the challenge page asks for. Caddy also serves the
pensive, happy and reject artwork from assets/anubis/. Edit the stylesheet
or replace those images to customize the screen; changes show up on the next page
load.
The challenge wording and Anubis/Techaro service attribution remain upstream. Omicron hides the upstream mascot-artist credit because its original artwork is replaced. Custom titles or removing the service attribution are available through BotStopper.
The wording is already translated, and by the challenge service rather than by
Omicron: it reads the visitor’s Accept-Language header and renders in whichever
of its 25 languages matches — Polish, Italian, Turkish, Ukrainian, Chinese and
others — falling back to English. Azerbaijani is not among them. The one part
that stays English whatever it picks is the footer line and imprint page above,
which are your instance’s own words; translate them in botPolicy.yaml if your
readers need it.
IP access rules
In Admin → Security → IP access rules, an admin can temporarily allow or block an IPv4/IPv6 address or CIDR range without editing deployment files. These rules apply even when AI-scraper protection is off. No rules are configured by default.
- Enter an IP address or CIDR range, such as
192.0.2.10or2001:db8::/64. Use a single address where possible; a network range can affect many readers. Use plain IPv4 rather than IPv4-mapped IPv6 ranges; scoped IPv6 addresses such as link-local addresses with an interface suffix are not accepted. - Choose Block web pages (403) or Allow without an Anubis challenge. Allowing does not bypass sign-in, authorization, or rate limits.
- Choose an expiry: 1 hour, 24 hours (the default), 7 days, or 30 days. Permanent rules are not supported. Add an optional reason (up to 300 characters).
- Before applying, enter a visitor IP and URL path under Test an IP and path, then select Test draft rule. The draft takes precedence for this preview only. Test saved rules checks the current stored list. Neither button changes the live configuration or simulates Anubis’s built-in bot policy.
- Select Apply rule. A successful save takes effect immediately through Caddy. Invalid configuration is rejected without replacing its running configuration; an error keeps your form input available to correct.
The first enabled, unexpired matching rule wins, newest first. A newer allow can make an exception to an older block. Disable a rule to stop applying it, re-enable it before its expiry, or remove it. Removing is immediate; it does not wait for expiry. There is a limit of 100 unexpired rules, including disabled ones. Expired rules cannot be re-enabled; they can be removed and are pruned when another rule is added.
Expiry is checked by Caddy on each request, without a restart or cleanup timer. Saved rules are restored when the backend reconciles Caddy after a stack restart; there is a brief fail-open window while Caddy becomes reachable.
Compatibility and recovery paths are exempt from custom IP rules: the API,
federation/discovery, feeds and sitemaps, robots.txt, IndexNow verification,
app/challenge assets, /admin, /login, and account-recovery pages. Exemption
leaves the normal routing and Anubis policy intact; a sign-in/admin page may
still show the ordinary challenge when protection is on. A custom block is
therefore not a complete ban on API access, federation, or authentication.
The list remains readable and previews remain available without a managed
proxy, but changing rules requires a managed Caddy deployment. If applying a
rule reports a missing configuration marker, follow the
one-time upgrade steps.
Advanced bot/path rules remain in botPolicy.yaml; the UI does not edit that
file or provide request logs.
Media
Optional. Controls where writers can search for a post banner from inside the editor.
Openverse is always available and needs nothing configured — no account, no key. Every instance has working photo search out of the box.
Unsplash is opt-in, and opt-in by necessity: Unsplash issues a key per registered application and has no anonymous mode, so unlike Openverse it cannot work untouched. Create a free app at unsplash.com/oauth/applications and paste its Access Key here to add Unsplash as a second tab in the picker. Their demo tier allows 50 searches an hour across the whole instance, shared by every writer on it.
The key is write-only: the panel reports whether one is set and never reads it back to the browser. To change it, enter the new one; to turn Unsplash off, remove it — Openverse keeps working either way.
Analytics and discoverability
The Instance tab contains two separate analytics controls:
- On-instance view counting controls built-in writer statistics, described in Writer dashboard.
- Umami Cloud connects an optional third-party website-statistics service. Paste a website ID or tracking snippet, enable it, and save. Both tracker and collection requests use the instance’s domain; no proxy configuration is needed. Unlike built-in counts, this forwards visitor IPs and browser information to Cloud. See the Umami Cloud setup and privacy guide before enabling it.
Discoverability holds the search-engine indexing switch, the sitemap,
robots.txt, per-console verification tokens, and IndexNow — see
Discoverability.
Everything is reversible
No admin setting requires a reinstall to undo. The ones that need a restart say so; the rest apply immediately.
Found a mistake?Edit this page on GitHub.