Skip to main content

I just forked Orkestra — now what?

This page assumes you've just clicked Fork on github.com/orkestra-cc/orkestra (or you're following the project as a contributor on a clean machine). It walks you from git clone to a logged-in admin console in about ten minutes.

If you only need to evaluate Orkestra, the README quick-start is shorter — it pulls a pre-built image from GHCR. Come back here when you want to modify the codebase.

What you'll need​

  • Docker 24+ with Compose v2. Linux/macOS/WSL2. Docker Desktop is fine.
  • openssl on your PATH (every distro has it).
  • make on your PATH.
  • About 2 GB of disk for images + first-boot caches.
  • ~10 minutes.

Optional (for backend development, not for just running the stack):

Step 1 — Clone​

git clone https://github.com/<your-org>/orkestra.git
cd orkestra

Throughout this guide, replace <your-org> with your GitHub user or organization name.

Step 2 — Bootstrap secrets and JWT keys​

make init

make init (defined in the Makefile, implemented in scripts/init.sh) is idempotent and does three things:

  1. Copies docker/.env.example → docker/.env.
  2. Fills five REPLACE_WITH_RANDOM_HEX_* placeholders with openssl rand output: COOKIE_SECRET, OAUTH_TOKEN_ENCRYPTION_KEY, ORKESTRA_KMS_MASTER_KEY, MONGO_ROOT_PASSWORD, REDIS_PASSWORD.
  3. Runs scripts/generate-jwt-keys.sh to produce an RS256 key pair under docker/keys/.
  4. Creates the orkestra-network Docker bridge.

The output prints the four next steps with copy-paste-ready commands.

Re-running make init is safe — existing files are preserved. Pass --force if you want to regenerate everything from scratch (this will invalidate every issued JWT).

tip

Both docker/.env and docker/keys/jwt-private.pem are gitignored. Don't commit them. If you ever need to share secrets across machines, use a real secret manager.

Step 3 — Start infrastructure​

cd docker
docker compose -f docker-compose.infra.yml up -d

This boots MongoDB (port 27027 on host), Redis (port 6387), and RustFS (S3-compatible blob storage). That's the whole infra base — the core-only build needs no addon-specific services.

Verify with:

docker compose -f docker-compose.infra.yml ps
# orkestra-mongodb   Up X seconds   (healthy)
# orkestra-redis     Up X seconds   (healthy)

Step 4 — Start the backend (dev stack with hot reload)​

From the repo root:

./orkestra.sh        # pick "Full stack" from the menu — or manually:
cd docker
docker compose -f docker-compose.dev.yml --env-file .env up -d

This builds docker/Dockerfile.dev-backend (public golang:1.25.10-alpine, AIR pre-baked — no registry auth) and boots the backend (AIR hot-reload) plus both frontends (Vite HMR). First boot takes ~30 s while it builds the image and runs go mod download; subsequent restarts are instant. A fork with a Chainguard subscription can swap the base image via the GO_BASE build-arg — see dev-images.

If you've pushed your own backend image to a registry, override BACKEND_IMAGE_REPO — see the README "Forking the image registry" section.

Step 5 — Verify the backend is healthy​

curl -s http://localhost:3000/health
# {"checks":{"mongodb":"up","redis":"up"},"status":"healthy","time":"...","version":"1.0.0"}

If you see mongodb:"down" or redis:"down", the infra compose didn't start cleanly — check docker compose -f docker-compose.infra.yml logs.

Step 6 — Create the first administrator and log in​

Open the operator console (http://localhost:8080). On a fresh install the setup wizard prompts you to create the first administrator — it posts to POST /v1/setup/admin, which is gated to first-install only (GET /v1/setup/status reports whether the system is still uninitialized). After that, log in normally with the credentials you just set.

Roles, highest to lowest: super_admin → administrator → developer → manager → operator → guest.

Step 7 — Add and enable modules​

Once logged in, navigate to /admin/modules. The core-only base ships only the seven core modules — there are no optional modules to toggle yet. To add one, create backend/internal/addons/<name>/ plus a cmd/server/catalog_<name>.go in your fork; it appears here and the registry hot-loads it (no restart, transitive dependencies auto-resolved). See Build your first addon.

See Enabling Modules for the per-module configuration UI.

Step 8 — (Optional) Configure OAuth providers​

Email/password login works out of the box. To add Google / Apple / GitHub / Discord SSO, follow OAuth Providers.

For local development, also set ALLOW_LOCALHOST_REDIRECTS=true in docker/.env so the OAuth callback flow accepts http://localhost.

What's next​

You now have a running Orkestra. Common next steps:

Common first-fork gotchas​

Port 3000 already in use​

Another process owns the port. Either stop it, or override BACKEND_PORT=3100 in docker/.env and re-run docker compose up.

make init says "openssl: command not found"​

You're on a stripped-down distro. apt install openssl or equivalent.

Container exits immediately​

docker compose -f docker-compose.dev.yml logs --tail 50 orkestra-backend-dev

Most-common causes:

  • JWT keys missing in docker/keys/ → re-run make init.
  • Mongo / Redis password mismatch between docker/.env and what the infra compose used → docker compose -f docker-compose.infra.yml down -v (wipes data!) + re-init.

See Troubleshooting for the full catalog.