Quick start with docker-compose

The core super-repo wires ~20 service repos (git submodules) plus Postgres, Redis, and an Azure Blob emulator into a single make up. This is the fastest on-ramp: clone, drop in a GitHub token, and one command builds every image and starts the whole backend stack — healthy, with zero external accounts. For the manual, run-each-service-by-hand path, see Run from source.

What you need first

Just git, docker, and docker compose v2, plus a GitHub token (below). uv / go / node are optional — only needed to run a service outside Docker. Full list on Prerequisites.

The happy path

1. Clone with submodules. Every service is a branch-tracked submodule; the --recurse-submodules flag pulls them all. (Forgot it? Run git submodule update --init --recursive.)

   git clone --recurse-submodules <core-repo-url> core
   cd core

2. Bootstrap. make bootstrap is idempotent: it checks prerequisites, syncs submodules to their tracked branches, and creates .env from .env.example — generating a fresh INTERNAL_RPC_SECRET so the dev stack never runs on the placeholder.

   make bootstrap

3. Add a GitHub token. Every backend image pulls private soundverse-* dependencies at build time (via a BuildKit secret), so builds fail without a token. Put GH_TOKEN in .env with scopes repo + read:packages, or just run gh auth login — the scripts fall back to gh auth token.

4. Bring it up. make up builds every image and starts the backend stack detached. First run pulls base images and compiles Go + Python deps, so give it a few minutes.

   make up

5. Verify health. make doctor checks your tooling, the token, container state, and probes every host port.

   make doctor

Already have the services as plain clones?

If you obtained the repos as sibling clones (not yet a super-repo), run make wire once to adopt them as git submodules, then follow the flow above.

What comes up

The default profile is the backend only. make up prints the host→container endpoints; make doctor re-probes them (core-identity and core-mcp expose an HTTP /healthz; the rest are checked as raw TCP):

Service	Host port	Protocol
core-database	8080	Connect / h2c — the only DB writer
core-identity	8001	HTTP /healthz
core-storage	8081	gRPC
core-mcp	8090	h2c /mcp, /healthz
core-gateway-consumer	8082	gRPC — the consumer entrypoint
postgres	5432	—
redis	6379	—
azurite (blob emulator)	10000	—

Add the frontends with make up-frontend (behind a compose frontend profile): soundverse-saas-2.0 on http://localhost:3000 and the standalone UI2.0 studio on http://localhost:3001. See Run the frontends.

Daily commands

the ones you'll actually use

make up               # build + start the backend stack (detached)
make up-frontend      # + the SaaS app and UI2.0
make ps               # container status
make logs             # tail all   (one service:  make logs s=core-mcp)
make doctor           # tools + token + container health + ports
make down             # stop & remove containers (keeps data volumes)
make update           # pull latest of every submodule's tracked branch
make azurite-init     # create blob containers (once, before exercising uploads)
make agent-tool-id    # print the Agent One tool id for AGENT_TOOL_ID
make db-reset         # wipe Postgres + reload schema (DESTRUCTIVE)
make help             # the full list

The complete target reference lives in Make targets & Redis keys.

What boots free vs. what needs a secret

make up yields a fully healthy backend with no external credentials — all inter-service calls, the database, queues, and the tool registry work offline. Only features that reach outside the stack need a value in .env (names only — see Configuring .env and the full matrix on Offline vs. secrets):

Feature	Needs (by name)	Without it
Blob uploads (tool outputs)	run make azurite-init	storage boots; uploads 404 until the containers exist
Agent One LLM turns	LITELLM_API_KEY	the agent worker registers but can’t run a turn
Sansaarm song generation	SANSAARM_API_KEY, SANSAARM_API_BASE_URL	the worker registers but can’t generate
Browser login (end-to-end chat)	a real OIDC app credential	the UI loads but can’t authenticate

Uploads need the blob containers created once

Azurite starts empty. Until you run make azurite-init (which creates the private / public / live containers), any tool that uploads a result gets a 404. There is no mock storage provider — Azurite (or real Azure Blob) is required for the media path. See Storage & media plane.

Browser auth uses Logto (not Zitadel)

The fleet migrated to Logto; the platform token must be a JWT, which requires requesting an API resource in the OIDC app. The local .env.example still ships AUTH_*-prefixed auth vars pending the rename, so match the names in your copy. Full setup: Configure Logto OIDC. Service-to-service and backend-only work needs none of this.

The gotchas that bite

Schema init only runs on an EMPTY data volume

core-database runs no migrations — it expects the schema to already exist and pings the prod database at startup. Postgres loads the per-domain schema.sql files (mounted read-only from soundverse-proto) only on first boot of an empty volume. If init half-ran, or you changed the proto schema (make update first), force a clean reload with make db-reset (destructive — it drops the DB).

INTERNAL_RPC_SECRET and ENVIRONMENT must match everywhere

Every service reads one shared INTERNAL_RPC_SECRET from .env; a mismatch makes a worker fail to register and chat calls hang on “planning…” or return NotFound. ENVIRONMENT must also be identical across gateway, MCP, and workers — the tool registry is scoped by it, so a mismatch shows an empty AI Tools panel. See Troubleshooting.

Everything inside the stack is plaintext

Local inter-service links are h2c / gRPC with TLS off (*_USE_TLS flags set to false). That’s expected for dev; TLS is only enforced at the deployed edge.

What’s in the box

• Directorycore/

  • docker-compose.yml the full stack
  • .env.example copy → .env
  • .gitmodules the ~20 service repos + tracked branches
  • Makefile make help
  • Directoryscripts/ bootstrap / up / update / doctor / wire

    • …
  • Directorycompose/postgres/ schema init (prelude + loader)

    • …
  • update-all-protos.sh refresh every service’s generated stubs

Related

• Prerequisites & toolchains — what to install first
• Configuring .env — the shared secret + injection pattern
• Run from source — the manual, per-service bring-up
• Offline vs. secrets — the full capability matrix
• Repository catalog — every submodule, one per row
• Troubleshooting — the one-line fix for each failure