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:
- Detects your container engine (
docker compose,docker-compose,podman compose, orpodman-compose). - Pulls the prebuilt images of the stable channel, the newest release.
- 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. - Saves the channel to
.env, runscompose 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
secretsvolume; - 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.