Skip to content
Omicron

Self-hosting

Security

The security properties of a default install, and the handful of things an operator can get wrong.

What is secure by default

  • Debug ports are loopback-only. The backend (:8000) and frontend (:5173) are published on 127.0.0.1 for local troubleshooting. All public traffic goes through Caddy on 80/443 over TLS.
  • Secrets are generated, never typed. The database password and session secret are created on first boot into the secrets volume.
  • HTTPS is automatic. Certificates are fetched on demand and renewed by Caddy, and only for your saved domain and its www. alias.
  • Sessions are server-side. Session records live in Postgres behind an httpOnly cookie; there is no session state in the token itself.
  • Rate limiting is on for logins, registrations, API writes, remote discovery, the federation inbox, and the content webhook.
  • Webhook credentials are stored hashed. Publishing tokens are SHA-256’d before they touch the database, so a dump cannot be replayed against the endpoint. Unknown or revoked credentials get a flat 401, and a token can only ever create posts for the account that minted it.
  • The federation inbox is capped. Oversized payloads are rejected by declared length and again while buffering, so a missing or spoofed Content-Length cannot stream an unbounded body into the parser.
  • Caddy administration is isolated. Only Caddy and the backend share the admin Unix socket; other stack containers cannot reach an admin TCP port. The TLS certificate-approval endpoint is blocked at both public proxy layers.

Traffic protection and IP rules

Admin → Security contains the optional Anubis challenge switch and temporary IP access rules. They are separate controls: the challenge is off by default, while custom rules apply independently once saved.

An IP allow rule skips Anubis on matching web pages, not authorization or rate limits. A block returns 403 on matching web pages. API, federation, feeds, sitemaps, and sign-in/admin recovery paths retain their normal policy and are exempt from these custom rules. Newest enabled, unexpired matches win; all rules expire within 30 days.

This is not a host firewall. It uses Caddy’s direct peer address and must not be used behind a separate proxy/CDN in this version. Manage host/provider firewall rules independently, keeping SSH and the public HTTP/HTTPS entrypoint reachable. See the UI walkthrough and upgrade step.

Browser policy

Production pages use a nonce-based script and style-element policy. Images are restricted to the instance, data: previews, and blob: previews; HTTPS pages also send upgrade-insecure-requests. Tiptap’s injected stylesheet uses the page nonce.

Style attributes use unsafe-hashes with a fixed SHA-256 allowlist, not a blanket unsafe-inline allowance. It covers reviewed declarations for avatar sizes, visibility, hidden form controls, and fixed crop/navigation geometry. Hashes are never collected from rendered page or post HTML. Trusted client JavaScript still updates sizing and positioning through CSSOM.

Custom components that introduce new server-rendered style attributes need a stylesheet/class or a reviewed fixed declaration in apps/frontend/src/lib/server/styleCsp.ts. Do not hash arbitrary user content to make a CSP warning disappear. Public RSS and federation discovery keep their intentional public CORS behavior; it is not enabled for authenticated pages or private APIs.

Domain and mail hardening

These are domain-owner changes, not automatic consequences of upgrading the application. Export the DNS zone first, record the previous values, and make one change at a time. Do not replace working SPF, DKIM, or MX records with examples.

DKIM and DMARC

  1. Identify every legitimate sender for the domain, including services unrelated to Omicron. For API relay or SMTP delivery, use the provider’s DKIM records; Omicron’s generated DKIM keys are for direct sending, not a replacement for the relay provider’s keys.

  2. Inspect a real received verification or test message. Check Authentication-Results for dkim=pass with a signing domain aligned to the visible From domain, and dmarc=pass. A public DKIM TXT record alone does not establish that messages are correctly signed or aligned.

  3. Create and test a receiving mailbox or alias for aggregate reports. A sending service does not necessarily receive mail. A same-domain address avoids the extra authorization required for external DMARC report recipients.

  4. Replace the single _dmarc TXT record with monitoring plus that working address, for example:

    v=DMARC1; p=none; rua=mailto:dmarc@example.com
  5. After reports and received-message headers show all legitimate senders passing, change p=none to p=quarantine. Monitor delivery, then move to p=reject. Review the effect on subdomains too; do not enforce a policy blindly or publish multiple DMARC records at the same name.

Keep each provider’s existing return-path SPF/MX records. SPF records at the apex and at a sending subdomain are separate policies; do not add a second SPF record at either name.

CAA

Caddy’s default issuer fallback uses Let’s Encrypt and ZeroSSL. A CAA allowlist must permit both unless you deliberately configure a different issuer set. For that default configuration, add these records at the zone apex:

example.com. 3600 IN CAA 0 issue "letsencrypt.org"
example.com. 3600 IN CAA 0 issue "sectigo.com"

ZeroSSL’s CAA identifier is sectigo.com, not zerossl.com. Add an iodef contact only when its mailbox is monitored. Inventory other certificate users and subdomains first: an apex CAA policy can affect their renewals too. See Caddy issuer fallback and ZeroSSL’s CAA requirements.

DNSSEC

Enable zone signing at the authoritative DNS provider, verify that it publishes DNSKEY records and signatures, then publish the provider-generated DS values at the registrar. Do not invent a DS record or publish it before the matching signed zone is available: that can turn every validating lookup into SERVFAIL. Verify the chain with a validating resolver or DNSViz. Key rotation, changing DNS providers, and rollback also require coordinating the zone keys and parent DS.

HSTS preload

Omicron already sends a two-year HSTS policy with includeSubDomains over HTTPS. Preload is an optional extra, controlled by HSTS_PRELOAD=true (default false). The setting only adds the preload token; it does not submit the domain to browser lists.

Before enabling it, inventory every subdomain, confirm permanent HTTPS support and certificate renewal, and check the apex and www redirects. Recreate the frontend after changing the environment. Run the readiness check at hstspreload.org before submitting there as the domain owner. Browser-list removal can take months; turning the setting back off does not immediately undo a submission.

What you can get wrong

  • Do not disable rate limiting (RATE_LIMIT_ENABLED=false) unless a trusted upstream already throttles for you.
  • Do not leave the wizard unfinished on a publicly reachable server — the first person to complete it becomes the admin.
  • Do not store backups on the same machine, and remember that Method B backups contain your secrets.
  • Do not paste a publishing credential into a CMS template or a shared document. Whoever holds one can publish, edit, and unpublish posts as its owner. A per-user token is revoked from Settings → Integrations; WEBHOOK_SECRET is rotated by changing the value and restarting.

Rate limits

Defaults, tunable in .env:

Variable Default Limit
RL_LOGIN_MAX 15 login attempts per IP / 15 min
RL_REGISTER_MAX 5 registrations per IP / hour
RL_API_WRITE_MAX 120 writes / min per signed-in user (or per IP)
RL_UPLOAD_MAX 10 media uploads / min per signed-in user (or per IP)
RL_INBOX_MAX 300 federation inbox POSTs / min per source IP
RL_WEBHOOK_MAX 30 content-webhook POSTs / min per source IP
INBOX_MAX_BODY_BYTES 1000000 maximum inbox payload size
WEBHOOK_MAX_BODY_BYTES 512000 maximum content-webhook payload size
RL_REMOTE_MAX 30 anonymous remote-discovery GETs / min per IP
RL_REMOTE_MISS_MAX 20 cache-miss (outbound) remote lookups / min per caller
RL_REMOTE_MAX_OUTBOUND 10 global concurrent outbound federation lookups
RL_REMOTE_MAX_PER_ORIGIN 3 concurrent outbound lookups per remote host
REMOTE_LOOKUP_TIMEOUT_MS 10000 deadline for one WebFinger + actor + outbox lookup
REMOTE_NEGATIVE_CACHE_TTL_MS 60000 negative-cache time for failed/not-found lookups
REMOTE_CACHE_RETENTION_DAYS 30 days a cached remote actor survives unreferenced (0 disables pruning)

Cached remote actors and their posts are also pruned daily once they are stale and unreferenced — see REMOTE_CACHE_RETENTION_DAYS above — so a hostile instance serving many distinct actors cannot grow the database without bound.

Without Redis these counters are per-process and reset on restart. With REDIS_URL set they are shared and durable. See Rate limits.

Upload storage

Uploaded media is bounded by the upload rate limit above plus two storage quotas, enforced when the upload happens: UPLOAD_QUOTA_USER_MB (default 200 MB per account) and UPLOAD_QUOTA_TOTAL_MB (default 2048 MB per instance). 0 disables a cap; a breach answers the upload with HTTP 413. Unreferenced files are garbage-collected by a daily sweep after UPLOAD_GC_GRACE_DAYS (default 30) days, which is also why replacing an avatar does not free disk space immediately. Details in Environment → Upload storage.

Session secret rotation

Admin → Instance → Session secret rotates the secret that signs sessions. It signs everyone out — including you — and invalidates every JWT on the next restart. JWT issuance and public-key discovery pause until the restart completes. Use it only if you suspect exposure.

If you pinned SESSION_SECRET in the environment, rotate it there instead; an env-supplied value takes precedence over the stored one.

Federation exposure

Enabling federation opens a public, unauthenticated POST endpoint (the inbox) to the entire internet. Fedify verifies HTTP signatures on inbound activities, and the inbox is rate-limited and size-capped, but you are now a network participant:

  • Expect background noise from crawlers and probing servers.
  • Use Admin → Federation to defederate abusive domains; blocking also purges cached content from them.
  • Use Admin → Reports for user-reported content.

AI-scraper protection

Off by default. When on, it puts a proof-of-work interstitial in front of the interactive routes — composing, search, the dashboard, settings, admin, sign-in — and leaves alone everything a reader or a crawler fetches: articles, profiles, tag pages, feeds, sitemaps, the API, federation and OpenGraph crawlers. It is a bandwidth and abuse mitigation, not a security control, and it does not stop a scraper that executes JavaScript from reading your posts — see Admin panel.

A challenged request is answered with 503 and Retry-After, not 200, so an automated client is told the truth about what happened. Expect it in your monitoring; see what a challenged request gets back.

Set ANUBIS_REDIRECT_DOMAINS if you turn it on. Without it, the endpoint that redeems a solved challenge will forward a reader to any domain, which lets a link to your instance land the visitor elsewhere. See Environment variables.

Reader privacy

Built-in on-instance view counts are aggregate integers keyed by a one-way hash, with no IP address, fingerprint, or per-visit row stored for those counts. The full account, including what built-in analytics deliberately never collect, is in Writer dashboard.

Admins can separately opt into Umami Cloud, which forwards visitor IPs and browser information to a third party. It is disabled by default and is not part of the writer dashboard. Its same-origin proxy does not make that processing local-only; review the privacy requirements before enabling it.

The web UI fetches remote images through the instance’s image proxy. Remote image servers see the instance’s outbound address, not the browser’s address or session cookies. Private/reserved destinations, active image formats, and oversized transfers are refused. A legacy HTTP image must also be available over HTTPS to display. The instance still sees these image requests, and a link opened by the reader goes directly to its destination as usual. Stored post content and federated media URLs are not rewritten.

Keeping up to date

cd omicron && ./install.sh

Update regularly for security fixes; the installer backs up before every update. Test that your backups actually restore. Security fixes reach the edge channel as soon as they are merged, and stable with the next release. See Upgrading for source installs.

Reporting a vulnerability

Report security issues privately through GitHub security advisories rather than in a public issue, so a fix can ship before the details are public.

/.well-known/security.txt also publishes the project contact from SECURITY.md (security@omicron.blog). It remains accessible when bot protection is on.

Found a mistake?Edit this page on GitHub.