Prerequisites & toolchains

The whole 2.0 backend — ~20 submodules wired into one super-repo — runs on a laptop with no cloud dependencies. Two languages (Go + Python), one frontend (Next.js), and two stateful backends (Postgres + Redis). What you actually need to install depends on how much of the fleet you plan to run yourself.

Two paths, two toolchains

All-Docker (fastest)

make bootstrap && make up builds every image and starts the stack in containers. You only need git, Docker, and Docker Compose v2 on the host — plus a GH_TOKEN so BuildKit can pull the private soundverse-* deps. No Go, Python, or Node required. See Quick start with docker-compose.

From source (one service at a time)

Run the rest in Docker and rebuild the one service you’re editing on the host. Now you need that service’s toolchain: Go for the two Go services, Python + uv for everything Python, Node for the frontends. See Run from source.

make bootstrap gates on the required tools (git + Docker + Compose v2) and only warns about the optional ones — it is the fastest way to find out what’s missing on your machine.

The required tools

Versions below are verified against the repos, not the onboarding guide (which lags ~2 weeks). Go’s auto-toolchain means a single recent go on your PATH will fetch the exact version each go.mod pins, so you don’t have to hand-install both 1.25 and 1.26.

Tool	Version	Needed for
git	any recent	Cloning the super-repo and its submodules
Docker + Docker Compose v2	any recent	The stateful bits and the whole all-Docker path
Go	1.25+ (core-mcp pins 1.26.4)	Building/running core-database and core-mcp from source
Python + uv	3.14, latest uv	Every Python service and tool worker
Node + npm	20+ (built images use Node 22)	The soundverse-saas-2.0 frontend (and UI2.0)
Postgres	any recent (or Docker)	Backing store for core-database — default localhost:5432
Redis	any recent (or Docker)	Event streams, rate-limit counters, task-wake pub/sub — default redis://localhost:6379/0
buf	latest	Only when editing .proto contracts (see proto codegen)
gcloud / az	latest	Only for deploy or staging debugging — not needed to run locally

Why these exact pins

• Go: core-database/go.mod declares go 1.25.0 and core-mcp/go.mod declares go 1.26.4. Every Python service pins requires-python = ">=3.14".
• Node: the frontend has no engines field, but its Dockerfiles build on node:22, so Node 20 LTS or newer is the safe floor. The SaaS app is Next.js 15.
• All Python work goes through uv — the repos never call pip or manage a venv by hand.

Let Docker own the stateful bits

You don’t need Postgres or Redis installed on the host

Even on the from-source path, the common pattern is a throwaway docker run for each backing store — only the data plane needs something reachable at localhost:5432 and localhost:6379. The compose stack already runs Postgres, Redis, and Azurite (the local Azure Blob emulator) for you; make azurite-init creates the private / public / live containers that core-storage expects. Reach for a host-native install only if you have a specific reason to.

There is no automatic migration runner. The DDL ships next to the proto contracts as per-domain schema.sql files under soundverse-proto/proto/soundverse_proto/<domain>/v1/schema.sql; you load the ones your flow needs into Postgres before core-database starts. The all-Docker path does this wiring for you — see Run from source for the manual bring-up order.

Building images needs a GitHub token

Every image pulls private soundverse-* dependencies (the generated proto SDKs, the soundverse-py worker SDK), so BuildKit needs a token. Put a GH_TOKEN (name only — never commit the value) into .env, with scopes repo and read:packages, or run gh auth login. Without it, make up fails at the dependency-fetch step.

The shared internal secret is generated for you

make bootstrap writes .env from .env.example and fills in a freshly generated INTERNAL_RPC_SECRET — the bearer every internal gRPC call carries. Don’t hand-edit it to a placeholder, and keep it identical across all services. Full detail on the secret, the STAGING_/PROD_ injection convention, and the local *_USE_TLS=false flags is in Configuring .env. names only, never values

Only if you edit the contracts

buf is the odd one out: you install it only to regenerate SDKs after changing a .proto file (buf lint, buf generate, and the per-template variants). If you’re not touching soundverse-proto, skip it. The full ordered codegen recipe lives in Run proto codegen locally.

Related

Quick start with docker-composemake bootstrap → up → doctor — the fastest on-ramp.

Run the full stack from sourceThe bottom-up bring-up order for the core services and a worker.

Configuring .envINTERNAL_RPC_SECRET, prefix-strip injection, and local TLS-off flags.

Repository catalogEvery one of the ~20 submodules: repo, language, role, branch.