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:
- A tunnel (Cloudflare Tunnel, ngrok, tailscale funnel) pointed at your local
stack, with
APP_DOMAINset to the tunnel hostname. - 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
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 updaterFound a mistake?Edit this page on GitHub.