Skip to content
Omicron

Self-hosting

Installation

The two ways to install Omicron, what the installer does, and how to verify the stack came up correctly.

Option A — the installer

curl -fsSL https://raw.githubusercontent.com/the-jk-labs/omicron/main/install.sh | sh

The script:

  1. Detects your container engine (docker compose, docker-compose, podman compose, or podman-compose).
  2. Pulls the prebuilt images of the stable channel, the newest release.
  3. Downloads the few files the images run with (docker-compose.yml, Caddyfile, botPolicy.yaml, the Anubis theme, backup/restore.sh) into ./omicron, at the exact commit the images were built from.
  4. Saves the channel to .env, runs compose up -d, and prints the URLs to open.

No git and no build: the install takes about as long as the image download. To update later, run ./install.sh inside omicron. It backs up first; see Upgrading.

For every change as soon as it is merged, install the edge channel instead, or pin one release. See Release channels:

curl -fsSL https://raw.githubusercontent.com/the-jk-labs/omicron/main/install.sh | OMICRON_VERSION=edge sh

Installer options

All optional, set in the environment of the run:

Variable Default Purpose
OMICRON_VERSION stable stable, edge, or an exact version such as 2.1.0. Saved to .env.
OMICRON_REGISTRY ghcr.io/the-jk-labs Where images come from; the Docker Hub mirror works too. Saved to .env.
OMICRON_DIR omicron (. inside one) Install directory.
HTTP_PORT / HTTPS_PORT 80 / 443 Host ports, e.g. 8080/8443 for rootless Podman.
OMICRON_SKIP_BACKUP=1 off Update without the pre-update backup.
OMICRON_ALLOW_DOWNGRADE=1 off Move to an older version, or go on when GitHub can’t say. Needs a restore if older.
GITHUB_TOKEN — Any GitHub token; raises the limit for the installer’s version check.

Option B — build from source

git clone https://github.com/the-jk-labs/omicron.git omicron
cd omicron
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

docker-compose.build.yml adds the build sections, so this compiles the images from your working tree instead of pulling them. This is what you want if you run local changes. The first build takes a few minutes; later builds are cached and fast.

Running ./install.sh in a checkout switches it to the prebuilt images: the installer checks out the commit the images were built from instead of downloading the files.

What comes up

docker compose ps
Service Purpose Published on
caddy Public entrypoint, TLS termination, Let’s Encrypt 80, 443
frontend SvelteKit web app 127.0.0.1:5173
backend JSON API + ActivityPub (Deno) 127.0.0.1:8000
postgres Database internal only
redis Queue + rate-limit state internal only
anubis AI-scraper shield, in the path only when enabled internal only
backup Daily encrypted snapshots (restic) internal only
init-secrets Generates the secrets on first boot, then idles none

The frontend and backend ports are bound to loopback only. They exist for troubleshooting on the host; all public traffic goes through Caddy.

No configuration step

There is no .env to create. On first boot the stack generates:

  • the Postgres password, into the secrets volume;
  • the session secret, into the same volume;
  • the database schema, by running migrations automatically.

You only create a .env if you want to override a default — see Configuration.

Verify

curl localhost:8000/healthz     # {"status":"ok"}
curl localhost:8000/version     # {"name":"omicron","version":"…","federation":false}

Then open the app:

  • Local: http://localhost
  • Public: point DNS at the host first — Domain and HTTPS — then open https://your-domain.

Every route redirects to the setup wizard until it is finished. See Setup wizard.

Watching logs

docker compose logs -f            # everything
docker compose logs -f backend    # or: frontend, caddy, postgres, redis

The backend logs its version on boot, whether federation is enabled, and — in console email mode — every outgoing message with its link.

Stopping and removing

docker compose down      # stop, keep all data
docker compose down -v   # stop and DELETE all volumes

Found a mistake?Edit this page on GitHub.