diff --git a/.env.prod.example b/.env.prod.example index 6cddafe..675af68 100644 --- a/.env.prod.example +++ b/.env.prod.example @@ -1,6 +1,6 @@ -# Production configuration for compose.yml (no overlay needed — the base -# file is already the production shape: no published ports, everything -# reachable only on infra-net). +# Production configuration for compose.yml (no overlay needed: the base +# file is already the production shape, with no published ports and +# everything reachable only on infra-net). # # cp .env.prod.example .env.prod # chmod 600 .env.prod diff --git a/README.md b/README.md index 9b8f4a5..3976444 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,23 @@ # Infrastructure -The technology services shared by every project under `Documentos/` -(currently Musify, Ping and docker-manager): PostgreSQL, Zitadel (OIDC), +The technology services shared across projects (currently Musify, Ping and +docker-manager, each its own git repository): PostgreSQL, Zitadel (OIDC), SeaweedFS (S3-compatible storage), RabbitMQ and Jaeger. None of these have any business logic of their own, so instead of each project running (and provisioning, and keeping in sync) its own copy, they run once, here. +This repo doesn't assume anything about where the other projects are +checked out. Each one just needs a local path to this repo's checkout (see +"The Zitadel admin PAT" below), which you set once in that project's own +`.env`. + Each project keeps its own independent, fast `docker compose up` for the things that actually are its own: API/worker/gateway containers, database -migrations, its own OIDC apps and storage bucket (created against the shared -Zitadel/SeaweedFS below by its own `zitadel-init`/`seaweedfs-init` one-shot -jobs — see e.g. `Musify/MusifyM/deploy/compose.yml`). A project's dev stack -only needs this one already running; nothing here needs to know a consuming -project exists. +migrations, its own OIDC apps and storage bucket. Those get created against +the shared Zitadel/SeaweedFS below by the project's own `zitadel-init` and +`seaweedfs-init` one-shot jobs (see e.g. `Musify/MusifyM/deploy/compose.yml`). +A project's dev stack only needs this one already running; nothing here +needs to know a consuming project exists. ## What's here vs. what stays in each project @@ -23,7 +28,7 @@ project exists. | SeaweedFS (S3 storage) | The project's own bucket (`seaweedfs-init`), key layout | | RabbitMQ (broker) | The project's own exchanges/queues/consumers | | Jaeger (OTLP collector + UI) | The project's own instrumentation | -| — | LiveKit (Ping only — a single-project SFU with its own port range, not generalized) | +| (not shared) | LiveKit (Ping only, a single-project SFU with its own port range) | ## Running it @@ -36,8 +41,8 @@ That starts Postgres, Zitadel, SeaweedFS, RabbitMQ and Jaeger, with their ports published to `localhost`. Add `--profile tools` to also start pgAdmin. In production, the base `compose.yml` file **is** the production shape -already — no published ports, everything reachable only on the internal -`infra-net` network — so no overlay is needed: +already. There are no published ports, and everything is reachable only on +the internal `infra-net` network, so no overlay is needed: ```bash cp .env.prod.example .env.prod @@ -46,7 +51,7 @@ docker compose --env-file .env.prod -f compose.yml up -d ``` A consuming project's own production compose joins `infra-net` as an -external network to reach `postgres` / `zitadel` / `seaweedfs` / `rabbitmq` / +external network to reach `postgres`, `zitadel`, `seaweedfs`, `rabbitmq` and `jaeger` by container name (see Musify's `deploy/compose.prod.yml`). ### Ports (development) @@ -61,10 +66,10 @@ external network to reach `postgres` / `zitadel` / `seaweedfs` / `rabbitmq` / | pgAdmin (`--profile tools`) | `5050` | Postgres UI | A consuming project reaches all of these at `host.docker.internal:` -from inside its own containers — the same address the browser and the host -use — so the address is valid whichever way that project's own apps are +from inside its own containers. That's the same address the browser and the +host use, so it stays valid whichever way that project's own apps are running (in Docker or from the IDE). No shared Docker network is needed in -development; that's what keeps every project's own `up` independent and +development, which is what keeps every project's own `up` independent and fast, with this stack as the only prerequisite. ### Shared secrets @@ -73,17 +78,22 @@ fast, with this stack as the only prerequisite. `RABBITMQ_DEFAULT_USER`/`RABBITMQ_DEFAULT_PASS` and `PUBLIC_AUTH_URL` (i.e. `http://host.docker.internal:${ZITADEL_EXTERNAL_PORT}` in dev) are the values every consuming project's own `.env.example` copies and documents as "must -match this repo's `.env`" — this file is the source of truth for them. +match this repo's `.env`". This file is the source of truth for them. ### The Zitadel admin PAT `zitadel-init` (in the compose file of whichever project runs it first) writes a service-account personal access token to `zitadel/.output/admin-sa.pat` -on first init. Every consuming project mounts that same folder read-only — -by default at `../../../Infrastructure/zitadel/.output`, three levels up from -a `deploy/` folder — to call the Zitadel management API and create its own -project/apps. Not versioned; regenerated whenever the Zitadel volume is -reset. +on first init. Every consuming project mounts that same folder read-only, via +its own `ZITADEL_ADMIN_PAT_DIR` setting, to call the Zitadel management API +and create its own project/apps. + +That setting has no universally correct value. It's a path (relative or +absolute) to wherever *you* cloned this repo on your machine, from the +consuming project's `deploy/` folder. Each project's `.env.example` ships +with an example value that assumes these repos happen to sit as sibling +folders. If yours don't, change it. Not versioned, and regenerated whenever +the Zitadel volume is reset. ## Resetting @@ -93,14 +103,14 @@ docker compose -f compose.yml -f compose.dev.yml down -v # stop, wipe volu ``` Wiping the volumes resets Zitadel (all projects/apps/users) and SeaweedFS -(all buckets) — every consuming project's own `zitadel-init`/`seaweedfs-init` +(all buckets). Every consuming project's own `zitadel-init`/`seaweedfs-init` re-creates its piece on the next `up`, since both are idempotent. ## Layout ``` Infrastructure/ -├─ compose.yml # postgres, zitadel, seaweedfs, rabbitmq, jaeger — the prod shape +├─ compose.yml # postgres, zitadel, seaweedfs, rabbitmq, jaeger: the prod shape ├─ compose.dev.yml # dev overlay: publishes ports, adds pgAdmin ├─ .env.example / .env.prod.example ├─ postgres-init/ # creates the per-project application databases diff --git a/compose.yml b/compose.yml index 5f308fe..9dbf618 100644 --- a/compose.yml +++ b/compose.yml @@ -1,10 +1,10 @@ -# Shared infrastructure — identity, storage, database, messaging and tracing -# for every project under Documentos/ (Musify, Ping, docker-manager, ...). +# Shared infrastructure: identity, storage, database, messaging and tracing +# for every project (Musify, Ping, docker-manager, ...). # # This file is the production shape: no published ports, no domains. Every # service is reachable only on the `infra-net` network. Development reaches # it through compose.dev.yml, which publishes the ports to the host instead -# of joining a network — see README.md for why. +# of joining a network. See README.md for why. # # dev docker compose -f compose.yml -f compose.dev.yml up -d # prod docker compose --env-file .env.prod -f compose.yml -f compose.prod.yml up -d @@ -22,7 +22,7 @@ services: # --- Database --------------------------------------------------------- # One instance, one database per consuming project (see postgres-init/). # Zitadel provisions its own `zitadel` database itself, from the admin - # credentials below — it does not need an init script. + # credentials below, so it does not need an init script. postgres: image: postgres:17-alpine container_name: infra-postgres @@ -88,7 +88,7 @@ services: # S3-compatible object store shared by every project. All-in-one: master + # volume + filer + S3 gateway. The S3 identity file is rendered from the # environment on start so the credentials can never drift from the ones - # handed to consuming projects. No bucket is created here — each + # handed to consuming projects. No bucket is created here; each # consuming project's own seaweedfs-init one-shot creates its own. seaweedfs: image: chrislusf/seaweedfs:latest diff --git a/postgres-init/010-create-app-databases.sql b/postgres-init/010-create-app-databases.sql index 14a872f..df7030a 100644 --- a/postgres-init/010-create-app-databases.sql +++ b/postgres-init/010-create-app-databases.sql @@ -1,8 +1,8 @@ -- Runs once, only on first init of the postgres_data volume. -- Zitadel provisions its own "zitadel" database itself, from the --- ZITADEL_DATABASE_POSTGRES_ADMIN_* credentials in compose.yml — it does not --- need to be created here. This script only creates the plain application --- databases each project's own connection string points at. +-- ZITADEL_DATABASE_POSTGRES_ADMIN_* credentials in compose.yml, so it does +-- not need to be created here. This script only creates the plain +-- application databases each project's own connection string points at. CREATE DATABASE musify_db; CREATE DATABASE ping_db;