Self-hosting
Upgrading
One command, a backup first, automatic migrations, and the guarantee that upgrades never touch your data.
cd omicron
./install.sh
The installer updates to the newest version of your release channel, in this order:
- Takes a backup (
backup-now). If it fails, it stops and changes nothing. - Pulls the new backend image and reads which commit it was built from.
- Refuses if that is older than what runs now. Migrations only go forward.
- Fetches
docker-compose.yml, theCaddyfile,botPolicy.yamland the other deployment files at that commit. - Pulls the other images and starts the stack. If any deployment file changed,
it recreates every container, so none keeps an old
Caddyfilemounted. - Removes images nothing uses any more.
A source checkout that builds its own images updates with git pull and a
build. The build sections live in docker-compose.build.yml, added with -f:
git pull --ff-only
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
docker image prune -f
docker builder prune -f # or the equivalent podman commands
One-time step: moving a source install to prebuilt images
Instances installed before 2.1.0 build their own images from a git checkout. They can move to the prebuilt images, or keep building.
Before you start
- The stack must be running. The installer takes a backup before it changes anything, and stops if it can’t.
- Edited files git tracks, such as the
Caddyfile? Commit or stash them: the installer checks out a new commit and stops on local changes. - Your own
docker-compose.override.ymlstays as it is. It is yours: the repository doesn’t ship that name, and the installer never touches it. - Stay in the same directory. The volumes are named after it.
Move
Pipe the installer from inside the checkout. Don’t save it as install.sh there
first: that replaces a file git tracks, and the checkout then refuses to switch.
cd omicron
curl -fsSL https://raw.githubusercontent.com/the-jk-labs/omicron/main/install.sh | sh # edge
curl -fsSL https://raw.githubusercontent.com/the-jk-labs/omicron/main/install.sh | OMICRON_VERSION=stable sh # stable
| Channel | Choose it if |
|---|---|
| edge | You followed main with git pull and want to keep doing so. The default for these installs. |
| stable | You want releases only. Works when your checkout is no newer than the latest release. |
Before it changes anything, the installer asks GitHub whether the version you
chose is older than your checkout. If it is, or GitHub can’t answer, it stops;
see Release channels.
Then it backs up, pulls the images, checks out the commit they were built from
(a detached HEAD), saves the channel to .env, and recreates the stack. Later
updates are ./install.sh. Confirm with:
curl localhost:8000/version # the release you chose, or newer on edge
docker compose ps # Omicron images from ghcr.io/the-jk-labs
Or keep building from source
Nothing forces the move. Build with docker-compose.build.yml, as above:
git pull --ff-only
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
Federation network (auto-cache)
This release lets a federating instance cache the Omicron network in the
background. It is on by default, so the upgrade starts outbound requests
without any admin action. The migration adds two tables and one column, runs on
startup, and needs no environment variable. Existing domain blocks are unchanged:
the new severity column defaults to suspend, which is what they already do.
-
Take a backup and confirm the new snapshot exists. Stop on failure:
docker compose exec backup backup-now docker compose exec backup restic snapshots -
Run the upgrade commands at the top of this page. No Caddy recreation is needed.
-
Decide whether to keep auto-cache on. It starts on the first boot, and only while federation is on. Right away it:
- asks FediDB for every Omicron instance it lists, and tracks each one;
- reads each tracked instance’s NodeInfo and public feed, then caches recent public posts from up to 20 of its writers, every 6 hours by default.
These are plain HTTPS GET requests identifying the instance as
Omicron/<version> (+https://your-domain). No user data is sent. To stop them, open Admin → Federation → Federation network and switch off Auto-cache the network, which stops syncing and discovery. Switching off only Discover Omicron instances on FediDB stops discovery and leaves syncing running. Neither switch needs a restart. -
Check Admin → Federation shortly after startup. A FediDB error there does not stop the tracked instances from syncing; discovery retries within the hour.
Cached posts from an instance that stops being synced age out under
REMOTE_CACHE_RETENTION_DAYS (default 30), so expect the
database to hold more remote posts than before.
Web accessibility and content preservation
Deploy backend and frontend together for the accessibility controls and content-loss warnings. This change adds no migration, environment variable, or automatic content backfill.
-
Take a backup and confirm the new snapshot exists. Stop on failure:
docker compose exec backup backup-now docker compose exec backup restic snapshots -
Pull the release, rebuild, and recreate both application services:
git pull --ff-only docker compose up -d --build backend frontendPreserve all named volumes. Podman Compose users can run the equivalent commands. This change alone needs no Caddy recreation; older releases below may have their own one-time steps.
-
Check health and normal sign-in/reading, then confirm Image display in the navigation and the authoring controls below the article editor.
Federated body URL corrections apply to newly built Articles and later Updates; existing remote copies are not automatically resent. Metadata stripped from previously saved content cannot be recovered by this upgrade.
Follow-up: reference-safe paste and drop
If the accessibility release above is already installed, the paste/drop reference guard needs only a frontend rebuild. It adds no migration, environment variable, dependency change, or content backfill; it needs no backend restart or Caddy recreation. Older instances must still apply the combined upgrade above.
Take a fresh backup and confirm its snapshot first, using the commands above. Stop on failure. Retain the previous frontend image for rollback, preserve all volumes, and keep your usual Compose override files/options. Then run:
git pull --ff-only
docker compose up -d --build --no-deps frontend
Podman Compose users can run the equivalent commands. Check normal reading and sign-in, reload already-open editor tabs, and verify that a transfer with a missing description target waits for repair rather than offering to insert broken references. Existing articles are not automatically repaired or rewritten.
Follow-up: editor keyboard shortcuts
Instances that already have the accessibility release above need only a frontend rebuild for toolbar focus and link shortcuts. This follow-up adds no migration, environment variable, or dependency change; it needs no backend restart or Caddy recreation.
Take a fresh backup and confirm its snapshot using the commands above. Stop on failure, retain the previous frontend image for rollback, preserve all volumes, and keep your usual Compose override files/options. Then run:
git pull --ff-only
docker compose up -d --build --no-deps frontend
Podman Compose users can run the equivalent commands. Check normal reading and sign-in, then reload already-open editor tabs. Select a passage in the body, press Alt+F10, and confirm that Escape returns to the same selection. Check that Ctrl+K (Command+K on macOS) opens Add link for unlinked text and that cancelling leaves the text unchanged.
Follow-up: rapid keyboard selection before paste
Instances that already have the accessibility release above need only a frontend rebuild for the editor to apply the latest keyboard selection when a paste starts immediately after the final selection key. This follow-up adds no migration, environment variable, or dependency change; it needs no backend restart or Caddy recreation.
Take a fresh backup and confirm its snapshot using the commands above. Stop on failure, retain the previous frontend image for rollback, preserve all volumes, and keep your usual Compose override files/options. Then run:
git pull --ff-only
docker compose up -d --build --no-deps frontend
Podman Compose users can run the equivalent commands. Check normal reading and sign-in, then reload already-open editor tabs. Select a passage with the keyboard and paste immediately: the paste should replace only that passage, and undo should restore it. This fixes the reproduced stale-selection paste path, not every browser selection or navigation difference.
Better Auth, passkeys, and Android App Links
This release updates Better Auth, enables native Omicron app sign-in, and allows passkey assertions on the instance’s own origin. It also adds the optional Android App Links settings described in Environment variables. No database migration is required.
Before upgrading, create a backup and confirm the snapshot exists:
docker compose exec backup backup-now
docker compose exec backup restic snapshots
For omicron.blog, set ANDROID_APP_CERT_FINGERPRINTS in the deployment
.env to the SHA-256 fingerprints for the keys that sign the Android app.
Leave it unset on instances that do not publish that app. Then rebuild and
recreate the application services; Caddy must be recreated to load the updated
Caddyfile:
docker compose up -d --build
docker compose up -d --force-recreate caddy
Verify the public statement with
curl https://omicron.blog/.well-known/assetlinks.json. The Android verifier
and an installed release build still need to confirm the end-to-end link flow.
Content portability
The import/export workflow ships new backend routes and a Settings → Content tab. Deploy backend and frontend together. It adds no database migration or backfill.
-
Create a backup and verify that its new snapshot exists. Stop on failure:
docker compose exec backup backup-now docker compose exec backup restic snapshots -
Pull the release, rebuild, and recreate the affected services:
git pull --ff-only docker compose up -d --build backend frontendCompose picks up the frontend’s updated
BODY_SIZE_LIMIT=50m. Preserve all volumes. No Caddy recreation is needed for this release; Podman Compose users can run the equivalent commands. -
If you maintain a custom Compose file, frontend environment override, or gateway body cap, allow 50 MiB archive requests. The SvelteKit proxy still limits other API writes to 5 MiB; backend image limits remain unchanged.
-
Verify normal reading and sign-in, then open Settings → Content. A signed-out request to
/api/content/exportmust return401, not a ZIP. Use the preview to inspect an archive before importing. Do not use the integration test suite against your instance database.
Security-hardening upgrade
The remote-image proxy, browser policy, and Caddy admin socket must ship together. Do not deploy just the frontend: it will request an image endpoint the old backend does not provide. Do not reload only the Caddyfile: the old backend still expects the removed admin TCP listener.
-
Before upgrading, create a backup and verify the new snapshot exists:
docker compose exec backup backup-now docker compose exec backup restic snapshotsStop if the backup fails or the snapshot is missing. Keep an off-host copy and a tested restore procedure; see Backups.
-
Remove a legacy
CADDY_ADMIN_URL=http://caddy:2019override from.env, if present. The bundled stack now uses/run/caddy-admin/admin.sock; a nonempty custom URL takes precedence and would keep the toggle pointed at the old port. -
Pull the release containing the change and recreate the three services:
git pull docker compose up -d --build --force-recreate backend frontend caddyCompose creates the
caddy_adminvolume and mounts it only in Caddy and the backend. Do not delete existing database, upload, secret, or certificate volumes. Podman Compose users can use the equivalent commands. -
Check sign-in, remote avatars and article images, and the scraper-protection toggle in both directions. Confirm
/.well-known/security.txtis public and/api/instance/tls-check?domain=your-domainreturns404through the public entrypoint. Check Caddy and backend logs for socket or config-reload errors.
No schema migration or content backfill is required by these hardening changes. HTTP-only remote images may stop displaying: the proxy requires HTTPS. Style attributes are limited to fixed declaration hashes; custom server-rendered inline styles may need to move into a stylesheet. DNS/mail policy, DNSSEC, and CAA are separate operator work. HSTS preload remains off unless the owner opts in after checking the whole domain tree; see Security.
What happens
- Migrations run automatically on backend startup and are idempotent — a no-op when the schema is already current.
- An upgrade recreates containers but never volumes, so your data, secrets, and TLS certificates are preserved.
image prunedrops the previous version’s images once nothing uses them, and on source installsbuilder prunedrops the build cache, so upgrades never leave disk usage creeping up. Neither ever removes a named volume, so both are safe to run every time.- The app version is logged on boot and exposed at
GET /version.
Migration policy
Upgrades must never break a running instance, so schema changes are additive only within a version:
- Add new columns and tables (nullable or with defaults) and migrate data.
- Ship code that works with both the old and the new shape.
- Remove old columns only in a later major release.
Migrations are versioned SQL in apps/backend/drizzle/, replayed at runtime by
src/db/migrate.ts. drizzle-kit is not required inside the container.
One-time step: IP access rules
The IP access-rule UI needs a managed insertion marker in the shipped
Caddyfile. Existing deployments must pick up that file in both Caddy and the
backend; restart alone can leave a replaced bind-mounted file pointing at its
old contents.
-
Create a backup and verify its snapshot before upgrading:
docker compose exec backup backup-now docker compose exec backup restic snapshotsStop if either command fails or the new snapshot is missing.
-
Pull the release and recreate the affected services:
git pull docker compose up -d --build --force-recreate backend frontend caddy backupThe backup service also mounts the Caddyfile, so recreate it to keep future configuration backups current. Never delete named volumes. Podman Compose users can use the equivalent commands.
-
Open Admin → Security → IP access rules. Preview a draft against a test address and
/search, then against/admin; the latter must report an exempt path. A preview does not create a live block. Confirm normal sign-in, public reading, feeds, and API access still work.
This feature adds no schema migration or environment variable, and starts with no custom rules. A missing-marker error means the backend is still reading an older Caddyfile. Stored rules are re-applied after Caddy becomes reachable on startup; the short startup gap is fail-open, not a durable network firewall.
One-time step: the AI-scraper-shield release
That release changed the bundled Caddyfile to open an internal admin API the
scraper-shield toggle uses. Caddy only reads that file at startup, and a plain
up -d does not recreate an unchanged service — so recreate the containers once:
docker compose up -d --build --force-recreate
This recreates containers, never volumes, so all data and certificates
survive. If you skip it nothing breaks: the instance runs normally and protection
stays off (the default); you simply cannot switch it on in Admin → Security
until Caddy has been recreated. After that release, normal up -d upgrades
resume.
One-time step: the Redis 8 release
That release moved the bundled Redis from 7.4 to 8. Redis 7.4 is offered only under RSALv2 and SSPLv1, neither of which is an open-source licence; Redis 8 restores AGPLv3 as an option, matching Omicron’s own licence.
Nothing is required of you. Redis 8 reads the files 7.4 wrote, so a normal
git pull && docker compose up -d --build upgrades it in place. The backend logs
a few seconds of ENOTFOUND redis while the container is replaced, then
reconnects on its own.
One-time step: the scraper-shield fixes release
That release changed the bundled Caddyfile again, so it needs the same recreate as the original shield release:
git pull && docker compose up -d --build --force-recreate
A plain up -d leaves Caddy on the old file and the fixes silently do not apply.
What you get once it is recreated:
- The challenge page no longer hangs on “Calculating…” until the reader refreshes.
- Page loads no longer fail with a 500 when the reader’s IP arrives from a private network.
- The challenge signing key is generated once into the
secretsvolume, so restarts and upgrades stop re-challenging readers who already solved one.
Containers are recreated, never volumes, so data and certificates survive. If the shield is on, it drops for a few seconds while Caddy restarts and the backend re-applies it — readers see the site unprotected, not broken.
The release also adds ANUBIS_REDIRECT_DOMAINS. Nothing breaks if you leave it
unset, but a public instance should set it — see
Environment variables.
One-time step: the challenge status-code release
The release that made a challenge answer 503 instead of 200 touches two
files the containers only read at startup — botPolicy.yaml and the
Caddyfile — so it needs the same recreate:
git pull && docker compose up -d --build --force-recreate
A plain up -d leaves the challenge answering 200 with no Retry-After.
Nothing breaks either way; the point of the change is that automated clients —
search engines, uptime monitors, link checkers — stop being told a refusal
succeeded. See
what a challenged request gets back.
If you only edited botPolicy.yaml yourself and want it picked up without
recreating anything else, docker compose restart anubis is enough.
Identity OAuth
The identity OAuth release adds four tables (oauth_apps, oauth_requests,
oauth_codes, and oauth_tokens) through migration 0043_gorgeous_shape.
Migrations run automatically on backend startup. Existing usernames, posts,
sessions, and the NodeInfo software name remain unchanged. No new environment
variables are required.
-
Before updating, take a backup and verify the new snapshot exists:
docker compose exec backup backup-now docker compose exec backup restic snapshotsStop if the backup fails or the snapshot is missing.
-
Pull the release and recreate all services that build the new application or mount its updated proxy and bot-policy files:
git pull --ff-only docker compose up -d --build --force-recreate backend frontend caddy anubis backupThis refreshes
Caddyfilein the backend, Caddy, and backup containers, andbotPolicy.yamlin Anubis and backup. A plainrestartcan leave an old bind-mounted file in place. Preserve every named volume. Podman Compose users can use the equivalent commands. -
Validate the proxy configuration and check service status:
docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile docker compose psConfirm
/.well-known/oauth-authorization-serverreturns JSON with the instance’s canonical issuer,GET /api/v1/accounts/verify_credentialswithout a token returns401rather than a bot challenge, and NodeInfo still advertisesomicron. Check normal sign-in and reading. A complete third-party sign-in also requires a supported client; see Identity OAuth.
The new Caddy machine-endpoint routes are required for form-encoded OAuth clients; do not fix origin-check failures by disabling browser CSRF protections. The backend re-applies saved scraper-shield and access-rule settings when Caddy is reachable after startup. FediDB still needs its own Omicron support change; upgrading the instance alone does not remove that service’s software allowlist.
Third-party clients
The scoped client-authorization release builds on identity OAuth. Migration
0044_unknown_nico_minoru adds a refresh-token table and application/grant
permission fields. Existing applications, consent requests, codes, and access
tokens default to the original identity-only permission; an upgrade does not
give an already-connected application new powers. Existing clients need new
registration/consent to request broader API access.
No environment variable is added. Update backend, frontend, and proxy routing together:
-
Create a backup and confirm that the new snapshot exists:
podman compose exec backup backup-now podman compose exec backup restic snapshotsDo not proceed on a failed backup or missing snapshot. Keep every named volume, including database, uploads, certificates, and secrets.
-
Pull a release containing the feature and recreate the affected services:
git pull --ff-only podman compose up -d --build --force-recreate backend frontend caddy backupDocker Compose users can substitute
docker compose. The migration runs on backend startup. Recreating Caddy loads the new API routing, while recreating backend and backup refreshes their views of the bind-mountedCaddyfile. A plain restart or an unchanged Caddy container can keep the old routing. -
Validate configuration and status:
podman compose exec caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile podman compose psConfirm
/api/clientreports API version 1, OAuth metadata uses the correct canonical issuer, and API calls/preflights return API responses rather than Anubis challenge HTML. Test browser sign-in, normal reading, client consent, and revocation from Settings → Integrations → Connected applications.
All /api paths, OAuth token/revocation transports, and root health/version
routes go directly to the backend in the updated gateway. Browser consent
remains in SvelteKit. The updated backend enforces
origin checks for cookie-authenticated writes.
Do not apply this Caddy routing to an older backend: that would remove
SvelteKit’s form-origin protection without replacing it.
Custom proxies must preserve Authorization, the browser’s unchanged Origin,
methods, bodies, OAuth/CORS headers, and preflights; keep
/api/instance/tls-check inaccessible publicly. Do not rewrite a client’s Origin
to the instance origin or remove CSRF checks to make a client work.
See Third-party clients for protocol and permission details. Existing Mastodon apps do not become compatible merely because the instance supports these authorization endpoints.
Rolling back
Go back by restoring, not just by running older code. Take the backup from before the upgrade, then:
OMICRON_VERSION=<previous-version> OMICRON_ALLOW_DOWNGRADE=1 OMICRON_SKIP_BACKUP=1 ./install.sh
./backup/restore.sh <snapshot-id>
Without OMICRON_ALLOW_DOWNGRADE=1 the installer refuses to go back.
OMICRON_SKIP_BACKUP=1 keeps it from taking a new snapshot of the state you are
leaving; leave it out if you want that snapshot too. On a source install, check
out the previous tag and run docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build instead.
Never run this on a live instance
docker compose down -v # deletes every volume: database, uploads, secrets, certs
down (without -v) is safe — it stops containers and leaves your data alone.
Checking what you are running
curl localhost:8000/version
docker compose ps
docker compose logs --since 5m backendFound a mistake?Edit this page on GitHub.