Skip to content
Omicron

Reference

Environment variables

Every variable, its default, and when you would actually set it. All of them are optional.

You do not need a .env file. The stack starts with none at all; the installer creates one holding only the release channel. Add to it, next to docker-compose.yml, only to override a default.

Version

Written by the installer; change them, then run ./install.sh. See Release channels.

Variable Default Purpose
OMICRON_VERSION stable stable (newest release), edge (every merge to main), or an exact version such as 2.1.0.
OMICRON_REGISTRY ghcr.io/the-jk-labs Registry the Omicron images come from. The Docker Hub mirror is docker.io/omicronhq.

Instance identity

Variable Default Purpose
APP_DOMAIN localhost:5173 Public domain, no scheme, no trailing slash. Usually set via the wizard.
PUBLIC_APP_NAME Omicron Instance name shown in the UI.
Variable Default Purpose
PUBLIC_SOURCE_URL upstream Where the footer’s Source link points. Point at your fork when you run a modified build (AGPL-3.0 §13).
PUBLIC_STATUS_URL (empty) External status page linked from the footer and /status. Overridden by Admin → Instance when set.
PUBLIC_CONTACT_URL (empty) Contact page linked from the footer. Overridden by Admin → Instance when set.
PUBLIC_CONTACT_EMAIL (empty) Contact email shown on /contact. Overridden by Admin → Instance when set.
PUBLIC_ABUSE_EMAIL (empty) Abuse email shown on /contact. Falls back to the contact email. Overridden by Admin → Instance.

About, instance rules, and the privacy policy have no environment equivalent — they are managed in Admin → Instance → Public information only. Instance settings take precedence over every variable above.

Federation

Variable Default Purpose
FEDERATION_ENABLED false true enables ActivityPub (WebFinger, actor, inbox/outbox). Applied on restart. Needs a real domain and HTTPS to be useful.
ALLOW_PRIVATE_FEDERATION false true lets remote discovery talk to private hosts (loopback, RFC1918, .local, …) for testing against a LAN instance. Applied on restart. Never enable on an internet-reachable host.

Secrets

Normally auto-generated into the secrets volume on first boot — leave unset.

Variable Default Purpose
SESSION_SECRET (generated) Pin your own: openssl rand -hex 32. Takes precedence over a UI-rotated secret.
POSTGRES_USER omicron Bundled database user.
POSTGRES_DB omicron Bundled database name.
DATABASE_URL (bundled) Point at an external Postgres. Takes precedence over the generated password.

Redis

Variable Default Purpose
REDIS_URL (bundled redis service) Backs the rate limiter, Fedify’s KV + message queue, and the app job queue. Unset it to run entirely in-process.

The Compose stack sets this to its bundled redis service automatically. Leave it unset for local pnpm dev, or point it at your own Redis.

Better Auth’s authentication limiter uses this same Redis connection, with atomic counters shared across backend processes. Counters retain their remaining window across backend restarts. If Redis is unavailable, limiting falls back to each process’s memory; that fallback is not shared and resets on restart.

Rate limiting

Variable Default Purpose
RATE_LIMIT_ENABLED true Disable only behind a trusted upstream that already throttles.
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 Reject inbox POSTs larger than this.
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 lookups per remote host.
REMOTE_LOOKUP_TIMEOUT_MS 10000 Deadline for one WebFinger + actor + outbox lookup.
REMOTE_NEGATIVE_CACHE_TTL_MS 60000 How long a failed/not-found lookup is negatively cached.
REMOTE_CACHE_RETENTION_DAYS 30 Days a cached remote actor survives once nothing re-fetches it and no local user references it; 0 disables pruning.

Content ingestion

You normally set nothing here. Writers mint their own publishing tokens under Settings → Integrations and publish under their own names — see Content webhook.

The variables below only add an instance-wide fallback credential, for publishing without a user token (a migration script, an operator-run pipeline).

Variable Default Purpose
WEBHOOK_SECRET unset Instance-wide fallback credential. Minimum 16 characters.
WEBHOOK_AUTHOR oldest account Username that WEBHOOK_SECRET publishes as.
WEBHOOK_MAX_BODY_BYTES 512000 Reject an ingested body larger than this.

Email

Normally set in the wizard or admin panel, where there is a live test button. These are fallbacks.

Variable Default Purpose
EMAIL_TRANSPORT console console, smtp, relay, or direct.
EMAIL_FROM Omicron <no-reply@localhost> Sender address.
SMTP_HOST — SMTP server hostname.
SMTP_PORT 587 587 for STARTTLS, 465 for implicit TLS.
SMTP_USERNAME — SMTP username.
SMTP_PASSWORD — SMTP password or API key.
SMTP_TLS false true = implicit TLS (465); false = STARTTLS (587).
EMAIL_VERIFICATION_REQUIRED true New accounts must confirm their email before they can sign in ("false" disables).

Accounts

Variable Default Purpose
HIBP_CHECK_ENABLED true Refuse passwords found in Have I Been Pwned breaches. Uses k-anonymity: only a hash prefix leaves the server. "false" skips it (air-gapped installs).

The backend serves /.well-known/assetlinks.json when signing-certificate fingerprints are configured. Android uses this public statement to verify that the site is allowed to open links in the named app. With no fingerprints, the route returns 404; malformed fingerprints prevent the backend from starting.

Variable Default Purpose
ANDROID_APP_CERT_FINGERPRINTS (empty) Comma-separated SHA-256 signing-certificate fingerprints in AA:BB:… form.
ANDROID_APP_ID blog.omicron.app Android package name named in the Digital Asset Links statement.

The Omicron-operated omicron.blog instance sets the fingerprints for its Android app. Leave them unset on other instances unless you operate an app signed by those keys; otherwise the instance would claim an app it does not ship. Set these values in the deployment .env; Compose passes them to the backend. The endpoint works with federation disabled and is publicly accessible at /.well-known/assetlinks.json.

Public entrypoint

Variable Default Purpose
HTTP_PORT 80 Host HTTP port for Caddy.
HTTPS_PORT 443 Host HTTPS port for Caddy.

Changing these breaks standard automatic HTTPS — Let’s Encrypt validates over 80 and 443. Change them only when those ports are genuinely unavailable.

AI-scraper protection

Variable Default Purpose
CADDY_ADMIN_URL (empty) Optional custom admin HTTP URL; overrides the bundled Unix-socket transport when set.
ANUBIS_REDIRECT_DOMAINS (empty) Hostnames a solved challenge may send a reader back to, comma separated. Empty allows any domain.

The shield itself is turned on from Admin → Security, not from here. The bundled stack uses CADDY_ADMIN_SOCKET=/run/caddy-admin/admin.sock; do not restore the old http://caddy:2019 override.

Set ANUBIS_REDIRECT_DOMAINS on a public instance. Left empty, the endpoint that redeems a solved challenge will forward a reader to whatever domain a redir parameter names — so a link to your instance can deposit the visitor somewhere else, borrowing your domain for the hop.

List every hostname your instance answers on, not only the canonical one:

ANUBIS_REDIRECT_DOMAINS=example.com,www.example.com

A reader who arrived on www. solves the challenge on www. and is refused the redirect if it is missing from the list. This is why the value is not derived from APP_DOMAIN automatically — canonicalisation happens in the app, which sits behind the challenge service.

Networking and storage

Variable Default Purpose
PORT 8000 Backend listen port.
INTERNAL_API_URL http://backend:8000 How the frontend reaches the backend.
UPLOADS_DIR /data/uploads Where uploaded media is written.
STATE_DIR /data/state Where generated secrets are persisted when not supplied via env or files.

HSTS preload

Variable Default Purpose
HSTS_PRELOAD false Frontend-only opt-in. Exactly true adds preload to the existing HTTPS-only, two-year HSTS header with includeSubDomains. Other values leave the header unchanged.

Compose passes this value to the frontend. Recreate the frontend after changing it; no backend restart is required. Do not enable it until every subdomain is permanently HTTPS-ready. The flag does not submit or remove the domain from any browser preload list. See Security → HSTS preload.

Caddy administration

The bundled stack shares a Unix socket between Caddy and the backend only. There is no admin TCP listener on the Compose network. The backend uses it to apply the AI-scraper-protection toggle without restarting Caddy.

Variable Default Purpose
CADDY_ADMIN_SOCKET Unset in a bare backend; /run/caddy-admin/admin.sock in Compose Path to Caddy’s admin socket. Compose mounts the caddy_admin volume at /run/caddy-admin, read-only in the backend.
CADDY_ADMIN_URL Unset Optional HTTP admin URL for a separately managed Caddy. Takes precedence over the socket when nonempty. Keep it on a trusted private connection.
CADDYFILE_PATH /etc/caddy/Caddyfile The file read by the backend when applying the toggle; mounted read-only by Compose.

For a custom deployment, set the socket path in the backend’s environment and match Caddy’s admin address and the shared mount. The bundled Compose file fixes the socket path; changing only .env does not relocate it. Remove an old CADDY_ADMIN_URL=http://caddy:2019 override when upgrading the bundled stack: that listener no longer exists. See Upgrading.

Backups

Daily encrypted snapshots (database + uploads + state + secrets) via the built-in backup service. All optional — unset means the default, and the defaults already protect a fresh instance locally.

Variable Default Purpose
BACKUP_ENABLED true Set false to disable the sidecar entirely.
BACKUP_SCHEDULE 0 2 * * * 5-field cron, UTC. Daily at 02:00.
BACKUP_REPOSITORY /backups/restic Snapshot destination. Local path by default; s3:<endpoint>/<bucket> for R2, S3, MinIO, B2.
BACKUP_S3_REGION auto Region for S3-compatible backends (auto is what R2 wants; set a real region for AWS). Ignored locally. AWS_DEFAULT_REGION wins if set.
AWS_ACCESS_KEY_ID — Key for the off-site backend. Unused locally.
AWS_SECRET_ACCESS_KEY — Secret for the off-site backend. Unused locally.
BACKUP_KEEP_DAILY 3 Days of automatic (daily and startup) snapshots to keep, one per day; older ones are pruned after each run.
BACKUP_KEEP_WEEKLY 1 Weekly snapshots to keep.
BACKUP_KEEP_MONTHLY 0 Monthly snapshots to keep.
BACKUP_KEEP_MANUAL 5 Manual snapshots (backup-now, the installer’s pre-update backup) to keep, newest first. 0 keeps them all.

Verified against .env.example and docker-compose.yml in the app repo. See Backups and restore for operations.

Upload storage

Uploaded media — post images, avatars, the instance banner — is bounded three ways: a per-account upload rate limit (RL_UPLOAD_MAX, above), storage quotas, and garbage collection.

Variable Default Purpose
UPLOAD_QUOTA_USER_MB 200 Upload storage per account, in MB. 0 disables.
UPLOAD_QUOTA_TOTAL_MB 2048 Upload storage for the whole instance, in MB. 0 disables.
UPLOAD_GC_GRACE_DAYS 30 Days an unreferenced upload survives before the daily sweep deletes it.

A quota breach answers an upload with HTTP 413 naming the cap that was hit. Quota checks are transactional, so concurrent uploads cannot slip past a cap.

Nothing is deleted the moment a reference disappears. A daily sweep reaps a file only once nothing has referenced it for UPLOAD_GC_GRACE_DAYS — long enough that other instances which cached the URL have moved on. Replacing an avatar or deleting a post therefore leaves the old file on disk for up to a month before the sweep collects it. That delay is what keeps images working on the fediverse; it is not a bug.

BODY_SIZE_LIMIT (adapter-node’s request-body cap) is 50m in the bundled frontend image and docker-compose.yml, to allow content archive uploads. The SvelteKit API proxy separately caps raw POSTs to /api/content/preview and /api/content/import at 50 MiB, retaining 5 MiB for other API writes. The backend still enforces its own image and archive limits. The bundled Caddy gateway routes public API requests directly to the backend.

When running the production frontend outside the supplied image, set BODY_SIZE_LIMIT=50m in its environment. A lower adapter or custom-gateway cap rejects archives before they reach the backend. See Upgrading → Content portability.

Applying changes

docker compose up -d

Some services only read certain files at startup; if a release changes the Caddyfile, add --force-recreate once — see Upgrading.

Found a mistake?Edit this page on GitHub.