Skip to content
Omicron

Development

Local setup

Running the backend and frontend directly, without Docker, for development.

Two options: the full Compose stack (closest to production), or the two apps run directly (fastest feedback loop).

Option A — the Compose stack

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

Everything is wired, including Postgres, Redis, and Caddy. Good for testing upgrades, migrations, and anything involving the reverse proxy. docker-compose.build.yml adds the build sections, so --build compiles your working tree rather than pulling the published images. Set COMPOSE_FILE=docker-compose.yml:docker-compose.build.yml in your shell to drop the -f flags.

Option B — run the apps directly

You need Deno (it runs the backend), Node 26+ for the backend tests, pnpm 12.11+, and a running PostgreSQL with DATABASE_URL set. A local .env is loaded too; variables already set in the environment win.

# From the repository root, install the shared contract and both apps:
pnpm --dir packages/contract install
pnpm --dir apps/backend install
pnpm --dir apps/frontend install

Start the backend in one terminal:

pnpm --dir apps/backend dev   # http://localhost:8000

Start the frontend in a second terminal, also from the repository root:

pnpm --dir apps/frontend dev  # http://localhost:5173

Migrations run automatically on backend startup, so an empty database is fine.

Checks before you push

(cd apps/backend && pnpm fmt && pnpm check)
(cd apps/frontend && pnpm fmt && pnpm check)

pnpm check runs greenly: in the backend tsc, oxfmt, oxlint, and the unit tests; in the frontend oxfmt, svelte-check, oxlint, and Vitest. Run pnpm fmt first so formatting never fails the check.

Testing federation locally

Federation needs a publicly reachable HTTPS domain, which localhost is not. Two workable approaches:

  1. A tunnel (Cloudflare Tunnel, ngrok, tailscale funnel) pointed at your local stack, with APP_DOMAIN set to the tunnel hostname.
  2. A cheap VPS running the Compose stack on a real subdomain — closest to reality, and worth it before any federation-touching change.

Useful during development

curl localhost:8000/healthz
curl localhost:8000/version

# Email in console mode prints reset/verification links here:
docker compose logs -f backend

Creating a migration

cd apps/backend
# edit src/db/schema.ts, then:
pnpm db:generate          # writes new SQL into ./drizzle — commit it

See Database and migrations.

Project layout

apps/backend/      Hono + Fedify + Drizzle (runs on Deno)
apps/frontend/     SvelteKit + Bits UI + Tailwind + Tiptap
apps/mobile/       Expo (React Native) app for Android and iOS
packages/contract/ zod/mini schemas for every API response
docker-compose.yml The whole stack, on the published images
docker-compose.build.yml     Build sections for a source checkout
deploy.files       What an image install fetches next to its .env
Caddyfile          Public entrypoint config
install.sh         The installer and updater

Found a mistake?Edit this page on GitHub.