Skip to main content

Getting started

The fastest way to see Cairn running locally.

Prerequisites​

  • Docker + Docker Compose
  • (For development) Go 1.26 and Node 24+

Run the stack​

Cairn's infrastructure (Postgres + TimescaleDB + PostGIS, NATS, an S3-compatible store such as MinIO, and a mail catcher) runs in Docker; the core binary serves the API and the embedded web UI.

# in cairn-core
make dev-up        # postgres + nats + minio + mailpit
make dev-server    # core API + web UI on :8090
make dev-web       # SvelteKit dev server (HMR) on :5273

Then open the web UI and sign in with the bootstrap admin from your dev.env.

Add a provider worker​

Provider workers live in their own repos and connect to the same NATS. Run the one(s) you need against the dev stack:

# Strava (Go) — in cairn-provider-strava
export CAIRN_NATS_URL=nats://localhost:4222
export CAIRN_WORKER_ENROLLMENT_TOKEN=...   # from POST /admin/worker-enrollments
go run ./cmd/worker-strava

# Garmin (Python) — in cairn-provider-garmin
export CAIRN_NATS_URL=nats://localhost:4222
python -m cairn_garmin.main
tip

A worker's only contract with core is the proto messages + the NATS subjects — there is no shared code dependency. See Provider workers.

Next​