Skip to content
Omicron

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:

  1. Takes a backup (backup-now). If it fails, it stops and changes nothing.
  2. Pulls the new backend image and reads which commit it was built from.
  3. Refuses if that is older than what runs now. Migrations only go forward.
  4. Fetches docker-compose.yml, the Caddyfile, botPolicy.yaml and the other deployment files at that commit.
  5. Pulls the other images and starts the stack. If any deployment file changed, it recreates every container, so none keeps an old Caddyfile mounted.
  6. 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.yml stays 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.

  1. Take a backup and confirm the new snapshot exists. Stop on failure:

    docker compose exec backup backup-now
    docker compose exec backup restic snapshots
  2. Run the upgrade commands at the top of this page. No Caddy recreation is needed.

  3. 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.

  4. 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.

  1. Take a backup and confirm the new snapshot exists. Stop on failure:

    docker compose exec backup backup-now
    docker compose exec backup restic snapshots
  2. Pull the release, rebuild, and recreate both application services:

    git pull --ff-only
    docker compose up -d --build backend frontend

    Preserve 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.

  3. 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.

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.

  1. 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
  2. Pull the release, rebuild, and recreate the affected services:

    git pull --ff-only
    docker compose up -d --build backend frontend

    Compose 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.

  3. 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.

  4. Verify normal reading and sign-in, then open Settings → Content. A signed-out request to /api/content/export must return 401, 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.

  1. Before upgrading, create a backup and verify the new snapshot exists:

    docker compose exec backup backup-now
    docker compose exec backup restic snapshots

    Stop if the backup fails or the snapshot is missing. Keep an off-host copy and a tested restore procedure; see Backups.

  2. Remove a legacy CADDY_ADMIN_URL=http://caddy:2019 override 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.

  3. Pull the release containing the change and recreate the three services:

    git pull
    docker compose up -d --build --force-recreate backend frontend caddy

    Compose creates the caddy_admin volume 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.

  4. Check sign-in, remote avatars and article images, and the scraper-protection toggle in both directions. Confirm /.well-known/security.txt is public and /api/instance/tls-check?domain=your-domain returns 404 through 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 prune drops the previous version’s images once nothing uses them, and on source installs builder prune drops 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:

  1. Add new columns and tables (nullable or with defaults) and migrate data.
  2. Ship code that works with both the old and the new shape.
  3. 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.

  1. Create a backup and verify its snapshot before upgrading:

    docker compose exec backup backup-now
    docker compose exec backup restic snapshots

    Stop if either command fails or the new snapshot is missing.

  2. Pull the release and recreate the affected services:

    git pull
    docker compose up -d --build --force-recreate backend frontend caddy backup

    The 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.

  3. 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 secrets volume, 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.

  1. Before updating, take a backup and verify the new snapshot exists:

    docker compose exec backup backup-now
    docker compose exec backup restic snapshots

    Stop if the backup fails or the snapshot is missing.

  2. 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 backup

    This refreshes Caddyfile in the backend, Caddy, and backup containers, and botPolicy.yaml in Anubis and backup. A plain restart can leave an old bind-mounted file in place. Preserve every named volume. Podman Compose users can use the equivalent commands.

  3. Validate the proxy configuration and check service status:

    docker compose exec caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
    docker compose ps

    Confirm /.well-known/oauth-authorization-server returns JSON with the instance’s canonical issuer, GET /api/v1/accounts/verify_credentials without a token returns 401 rather than a bot challenge, and NodeInfo still advertises omicron. 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:

  1. Create a backup and confirm that the new snapshot exists:

    podman compose exec backup backup-now
    podman compose exec backup restic snapshots

    Do not proceed on a failed backup or missing snapshot. Keep every named volume, including database, uploads, certificates, and secrets.

  2. 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 backup

    Docker 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-mounted Caddyfile. A plain restart or an unchanged Caddy container can keep the old routing.

  3. Validate configuration and status:

    podman compose exec caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
    podman compose ps

    Confirm /api/client reports 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 backend

Found a mistake?Edit this page on GitHub.