@opengroundplan/core 0.1.1

package/templates/layers/docker-compose/files/.env.compose.example

@@ -0,0 +1,66 @@
+# Overrides for the local Compose stack. Copy the lines you need into .env — Compose
+# reads .env from the repo root automatically.
+#
+# Everything here is OPTIONAL and intentionally has no value: each default lives in
+# the compose/ fragment that owns the service, as `${VAR:-default}`. Setting a key
+# here overrides it; leaving it out keeps the fragment's default. Uncomment to use.
+#
+# The db-* and cache-* layers ship their own .env examples for the settings the
+# APPLICATION reads (DATABASE_URL, REDIS_URL, pool sizes, TTLs). These are the
+# container-side knobs only, and the port/credential keys are deliberately the same
+# names so one .env drives both sides.
+
+# ── project ─────────────────────────────────────────────────────────────────────
+# Docker network name shared by every service in the stack.
+# COMPOSE_NETWORK_NAME={{ solutionName | kebab }}-net
+
+# Uncomment BOTH lines only if the `docker` layer is also installed, which adds a
+# compose.yaml holding the app image. Compose prefers compose.yaml and would then
+# start the app WITHOUT these backing services; this merges the two into one project.
+# The separator is pinned because COMPOSE_FILE otherwise splits on ';' on Windows.
+# COMPOSE_PATH_SEPARATOR=:
+# COMPOSE_FILE=compose.yaml:docker-compose.yml
+
+# ── PostgreSQL ──────────────────────────────────────────────────────────────────
+# POSTGRES_IMAGE=
+# POSTGRES_HOST_PORT=
+# POSTGRES_DB=
+# POSTGRES_USER=
+# POSTGRES_PASSWORD=
+
+# ── MySQL ───────────────────────────────────────────────────────────────────────
+# MYSQL_IMAGE=
+# MYSQL_HOST_PORT=
+# MYSQL_DATABASE=
+# MYSQL_USER=
+# MYSQL_PASSWORD=
+# MYSQL_ROOT_PASSWORD=
+
+# ── MongoDB ─────────────────────────────────────────────────────────────────────
+# MONGO_IMAGE=
+# MONGO_PORT=
+# MONGO_REPLICA_SET=
+
+# ── Redis / Valkey (same keys — the service is named `redis` either way) ────────
+# REDIS_IMAGE=
+# VALKEY_IMAGE=
+# REDIS_HOST_PORT=
+# REDIS_MAXMEMORY=
+# REDIS_MAXMEMORY_POLICY=
+
+# ── RabbitMQ ────────────────────────────────────────────────────────────────────
+# RABBITMQ_IMAGE=
+# RABBITMQ_HOST_PORT=
+# RABBITMQ_MANAGEMENT_PORT=
+# RABBITMQ_USER=
+# RABBITMQ_PASSWORD=
+# RABBITMQ_VHOST=
+
+# ── NATS ────────────────────────────────────────────────────────────────────────
+# NATS_IMAGE=
+# NATS_HOST_PORT=
+# NATS_MONITORING_PORT=
+
+# ── Kafka ───────────────────────────────────────────────────────────────────────
+# KAFKA_IMAGE=
+# KAFKA_HOST_PORT=

package/templates/layers/docker-compose/files/compose/cache-none.yml

@@ -0,0 +1,3 @@
+# No cache container selected. This file exists so the root `include:` always
+# resolves — swap the include path to cache-redis.yml or cache-valkey.yml to add one.
+services: {}

package/templates/layers/docker-compose/files/compose/cache-redis.yml

@@ -0,0 +1,28 @@
+# Redis. Keys match .env.cache.example from the cache-redis layer, so one .env drives
+# both the container and the application's client settings.
+services:
+  redis:
+    image: ${REDIS_IMAGE:-redis:8-alpine}
+    restart: unless-stopped
+    ports:
+      - "${REDIS_HOST_PORT:-6379}:6379"
+    command:
+      - redis-server
+      - --appendonly
+      - "yes"
+      - --maxmemory
+      - "${REDIS_MAXMEMORY:-256mb}"
+      # Cache workload: evict the coldest key rather than failing the write.
+      - --maxmemory-policy
+      - "${REDIS_MAXMEMORY_POLICY:-allkeys-lru}"
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
+
+volumes:
+  redis-data:

package/templates/layers/docker-compose/files/compose/cache-valkey.yml

@@ -0,0 +1,27 @@
+# Valkey — the BSD-licensed Redis fork. Wire-compatible, so any Redis client works
+# against it unchanged; the service is still named `redis` so hostnames stay portable.
+services:
+  redis:
+    image: ${VALKEY_IMAGE:-valkey/valkey:9-alpine}
+    restart: unless-stopped
+    ports:
+      - "${REDIS_HOST_PORT:-6379}:6379"
+    command:
+      - valkey-server
+      - --appendonly
+      - "yes"
+      - --maxmemory
+      - "${REDIS_MAXMEMORY:-256mb}"
+      - --maxmemory-policy
+      - "${REDIS_MAXMEMORY_POLICY:-allkeys-lru}"
+    volumes:
+      - valkey-data:/data
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+      start_period: 5s
+
+volumes:
+  valkey-data:

package/templates/layers/docker-compose/files/compose/db-mongo.yml

@@ -0,0 +1,27 @@
+# MongoDB as a single-node replica set — that is what enables transactions and change
+# streams locally. Auth is off by design here; production credentials belong in MONGO_URI.
+services:
+  mongo:
+    image: ${MONGO_IMAGE:-mongo:8.0}
+    restart: unless-stopped
+    command: ["mongod", "--replSet", "${MONGO_REPLICA_SET:-rs0}", "--bind_ip_all"]
+    ports:
+      - "${MONGO_PORT:-27017}:27017"
+    volumes:
+      - mongo-data:/data/db
+    healthcheck:
+      # Doubles as the initiator: the first probe bootstraps the replica set, later
+      # probes just report its status.
+      test:
+        - CMD
+        - mongosh
+        - --quiet
+        - --eval
+        - "try { rs.status().ok } catch (e) { rs.initiate({ _id: '${MONGO_REPLICA_SET:-rs0}', members: [ { _id: 0, host: 'localhost:27017' } ] }).ok }"
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 10s
+
+volumes:
+  mongo-data:

package/templates/layers/docker-compose/files/compose/db-mysql.yml

@@ -0,0 +1,31 @@
+# MySQL 8.4 LTS — supported into 2032, unlike the 9.x innovation track which ships
+# a new incompatible minor every quarter.
+services:
+  mysql:
+    image: ${MYSQL_IMAGE:-mysql:8.4}
+    restart: unless-stopped
+    environment:
+      MYSQL_DATABASE: ${MYSQL_DATABASE:-{{ solutionName | snake }}}
+      MYSQL_USER: ${MYSQL_USER:-{{ solutionName | snake }}}
+      # Dev-only. Production reads these from a secret store, never from a file.
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-mysql}
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-root}
+    command:
+      # utf8mb4 end to end: the server default is still latin1 on some builds, and a
+      # mismatch only surfaces once real user data contains an emoji.
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_0900_ai_ci
+    ports:
+      - "${MYSQL_HOST_PORT:-3306}:3306"
+    volumes:
+      - mysql-data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-u", "root", "-p${MYSQL_ROOT_PASSWORD:-root}"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+      # First boot initialises the data directory, which is slow.
+      start_period: 30s
+
+volumes:
+  mysql-data:

package/templates/layers/docker-compose/files/compose/db-none.yml

@@ -0,0 +1,4 @@
+# No database container selected. This file exists so the root `include:` always
+# resolves — swap the include path to db-postgres.yml / db-mysql.yml / db-mongo.yml
+# to add one later.
+services: {}

package/templates/layers/docker-compose/files/compose/db-postgres.yml

@@ -0,0 +1,28 @@
+# PostgreSQL. Keys match .env.postgres.example from the db-postgres layer, so one
+# .env drives both the container and the application's connection settings.
+services:
+  postgres:
+    image: ${POSTGRES_IMAGE:-postgres:18-alpine}
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-{{ solutionName | snake }}}
+      POSTGRES_USER: ${POSTGRES_USER:-{{ solutionName | snake }}}
+      # Dev-only. Production reads this from a secret store, never from a file.
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+      # Deterministic collation, so ORDER BY matches between laptops and CI.
+      POSTGRES_INITDB_ARGS: --locale-provider=icu --icu-locale=und-x-icu
+    ports:
+      # 5432 inside the container is the protocol default; only the host side moves.
+      - "${POSTGRES_HOST_PORT:-5432}:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      # Depending services wait on this, not on the container merely starting.
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-{{ solutionName | snake }}} -d ${POSTGRES_DB:-{{ solutionName | snake }}}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 10s
+
+volumes:
+  postgres-data:

package/templates/layers/docker-compose/files/compose/queue-kafka.yml

@@ -0,0 +1,35 @@
+# Apache Kafka in KRaft mode — one process acting as both broker and controller,
+# no ZooKeeper. Single node, so every replication factor is 1.
+#
+# Two listeners on purpose: containers on this network connect to kafka:9092, while
+# tools on the host connect to localhost:${KAFKA_HOST_PORT}. A client is redirected to
+# whatever `advertised.listeners` names, so the host port appears in both places below.
+services:
+  kafka:
+    image: ${KAFKA_IMAGE:-apache/kafka:4.3.1}
+    restart: unless-stopped
+    environment:
+      KAFKA_NODE_ID: 1
+      KAFKA_PROCESS_ROLES: broker,controller
+      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
+      KAFKA_LISTENERS: INTERNAL://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093,HOST://0.0.0.0:${KAFKA_HOST_PORT:-29092}
+      KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:9092,HOST://localhost:${KAFKA_HOST_PORT:-29092}
+      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,INTERNAL:PLAINTEXT,HOST:PLAINTEXT
+      KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
+      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
+      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
+      # Consumers join instantly instead of waiting out the 3s production default.
+      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
+    ports:
+      - "${KAFKA_HOST_PORT:-29092}:${KAFKA_HOST_PORT:-29092}"
+    healthcheck:
+      test: ["CMD", "/opt/kafka/bin/kafka-broker-api-versions.sh", "--bootstrap-server", "localhost:9092"]
+      interval: 10s
+      timeout: 10s
+      retries: 15
+      start_period: 20s
+    # No volume: the image runs as a non-root user that cannot chown a fresh named
+    # volume, and a dev broker holding state across recreates causes more confusion
+    # than it saves. docs/local-stack.md shows how to add one if you need it.

package/templates/layers/docker-compose/files/compose/queue-nats.yml

@@ -0,0 +1,26 @@
+# NATS with JetStream enabled — without `-js` there is no persistence, no streams,
+# and no consumers, only fire-and-forget pub/sub.
+services:
+  nats:
+    image: ${NATS_IMAGE:-nats:2.14-alpine}
+    restart: unless-stopped
+    command:
+      - "-js"
+      - "--store_dir=/data"
+      - "--http_port=8222"
+    ports:
+      - "${NATS_HOST_PORT:-4222}:4222"
+      - "${NATS_MONITORING_PORT:-8222}:8222"
+    volumes:
+      - nats-data:/data
+    healthcheck:
+      # The image has no shell and no curl; /healthz on the monitoring port is the
+      # only probe available, and wget is present in the alpine variant.
+      test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:8222/healthz"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 5s
+
+volumes:
+  nats-data:

package/templates/layers/docker-compose/files/compose/queue-none.yml

@@ -0,0 +1,3 @@
+# No message broker selected. This file exists so the root `include:` always resolves
+# — swap the include path to queue-rabbitmq.yml / queue-nats.yml / queue-kafka.yml.
+services: {}

package/templates/layers/docker-compose/files/compose/queue-rabbitmq.yml

@@ -0,0 +1,27 @@
+# RabbitMQ with the management plugin. UI on http://localhost:15672.
+services:
+  rabbitmq:
+    image: ${RABBITMQ_IMAGE:-rabbitmq:4.3-management-alpine}
+    restart: unless-stopped
+    hostname: rabbitmq
+    environment:
+      RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER:-{{ solutionName | snake }}}
+      # Dev-only. Production reads this from a secret store, never from a file.
+      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:-rabbitmq}
+      RABBITMQ_DEFAULT_VHOST: ${RABBITMQ_VHOST:-/}
+    ports:
+      - "${RABBITMQ_HOST_PORT:-5672}:5672"
+      - "${RABBITMQ_MANAGEMENT_PORT:-15672}:15672"
+    volumes:
+      # The node name is derived from `hostname`, so keeping it fixed above is what
+      # lets this volume survive a recreate.
+      - rabbitmq-data:/var/lib/rabbitmq
+    healthcheck:
+      test: ["CMD", "rabbitmq-diagnostics", "-q", "check_running"]
+      interval: 10s
+      timeout: 10s
+      retries: 10
+      start_period: 30s
+
+volumes:
+  rabbitmq-data:

package/templates/layers/docker-compose/files/docker-compose.yml

@@ -0,0 +1,20 @@
+# Local backing services for {{ solutionName | title }}.
+#
+#   docker compose up -d          start everything
+#   docker compose ps             health of each service
+#   docker compose down -v        stop and delete the data volumes
+#
+# Service definitions live in compose/, one file per slot, so a slot can be swapped
+# by editing a single `include:` path instead of untangling one large file.
+name: {{ solutionName | kebab }}
+
+include:
+  - path: compose/db-{{ composeDb }}.yml
+  - path: compose/cache-{{ composeCache }}.yml
+  - path: compose/queue-{{ composeQueue }}.yml
+
+networks:
+  # Named explicitly so an app container defined elsewhere can join it as an
+  # external network — see docs/local-stack.md.
+  default:
+    name: ${COMPOSE_NETWORK_NAME:-{{ solutionName | kebab }}-net}

package/templates/layers/docker-compose/files/docs/local-stack.md

@@ -0,0 +1,135 @@
+# Local stack
+
+Backing services for {{ solutionName | title }} — database, cache, and message broker —
+as one Compose project.
+
+```bash
+docker compose up -d      # start
+docker compose ps         # health of each service
+docker compose logs -f    # follow
+docker compose down       # stop, keep data
+docker compose down -v    # stop, delete data volumes
+```
+
+## Layout
+
+```
+docker-compose.yml     project name, shared network, and the include list
+compose/db-*.yml       one database service
+compose/cache-*.yml    one cache service
+compose/queue-*.yml    one message broker
+.env.compose.example   optional overrides
+```
+
+The root file includes exactly one fragment per slot. Every slot has a `-none.yml`
+variant, so an unused slot is an empty compose file rather than a missing include.
+
+## Changing a service
+
+Edit the matching `include:` path in `docker-compose.yml`. To swap Postgres for MySQL:
+
+```yaml
+include:
+  - path: compose/db-mysql.yml
+```
+
+Run `docker compose down -v` first — the old service's volume is not reused, and two
+database services would otherwise contend for the same host port.
+
+## Configuration
+
+No value is hardcoded in a service definition. Each is `${VAR:-default}`, where the
+default lives in the fragment and the override goes in `.env` at the repo root. See
+`.env.compose.example` for the full key list.
+
+Connection settings the **application** reads (`DATABASE_URL`, `REDIS_URL`, pool sizes,
+TTLs) are owned by the `db-*` / `cache-*` layers and documented in their own env
+examples. The port and credential keys are shared by both sides on purpose, so changing
+`POSTGRES_HOST_PORT` in `.env` moves the container and the client together.
+
+## Connecting
+
+From the **host** (your app running under `npm run dev`, `uv run`, `dotnet run`), using
+the default ports:
+
+```
+PostgreSQL      postgres://{{ solutionName | snake }}:postgres@localhost:5432/{{ solutionName | snake }}
+MySQL           mysql://{{ solutionName | snake }}:mysql@localhost:3306/{{ solutionName | snake }}
+MongoDB         mongodb://localhost:27017/{{ solutionName | snake }}?replicaSet=rs0
+Redis/Valkey    redis://localhost:6379/0
+RabbitMQ        amqp://{{ solutionName | snake }}:rabbitmq@localhost:5672/   (UI: http://localhost:15672)
+NATS            nats://localhost:4222                              (monitoring: http://localhost:8222)
+Kafka           localhost:29092
+```
+
+From **another container**, use the service name and the internal port instead of
+`localhost`: `postgres:5432`, `redis:6379`, `rabbitmq:5672`, `nats:4222`, `kafka:9092`.
+
+The passwords above are the dev defaults. Production values come from a secret store,
+never from a file in the repo.
+
+## Adding the app to the stack
+
+Two options.
+
+**Join the existing network** from a separate compose file — nothing here changes:
+
+```yaml
+services:
+  app:
+    build: .
+    networks: [{{ solutionName | kebab }}-net]
+
+networks:
+  {{ solutionName | kebab }}-net:
+    external: true
+```
+
+**Or add a service to this project**, which gets ordered startup for free. Every
+service here has a real healthcheck, so `service_healthy` waits for readiness rather
+than for the container to merely exist:
+
+```yaml
+services:
+  app:
+    build: .
+    depends_on:
+      postgres:
+        condition: service_healthy
+    env_file: [.env]
+    ports:
+      - "3000:3000"
+```
+
+## If the `docker` layer is also installed
+
+That layer adds `compose.yaml`, which builds and runs the app image. Compose picks
+**one** entry point and prefers `compose.yaml` over `docker-compose.yml`, so
+`docker compose up -d` would start the app with none of the services below — with only
+a warning. Both files use the same project name, so merging them is one `.env` change:
+
+```dotenv
+COMPOSE_PATH_SEPARATOR=:
+COMPOSE_FILE=compose.yaml:docker-compose.yml
+```
+
+Pin the separator: `COMPOSE_FILE` otherwise splits on `;` on Windows and `:` elsewhere.
+After this, `docker compose up -d` starts the app and its backing services together,
+and the app reaches them at `postgres:5432`, `redis:6379`, and so on.
+
+## Notes
+
+- **Kafka has no volume.** The image runs as a non-root user that cannot take ownership
+  of a fresh named volume. If you need topics to survive a recreate, add
+  `KAFKA_LOG_DIRS=/var/lib/kafka/data`, mount a volume there, and run the service as
+  `user: root` — acceptable for a dev broker, not for anything else.
+- **MongoDB self-initialises its replica set** through its healthcheck. The first probe
+  runs `rs.initiate`, so the service reports unhealthy for a few seconds on first boot.
+- **The `queue-broker` layer runs on Redis** for TypeScript/Node (BullMQ) and Python
+  (Celery), and ships its own `docker-compose.queue-redis.yml`. If the cache slot here
+  is already `redis` or `valkey`, that broker has its server — use it and delete the
+  extra file, or the two will contend for port 6379.
+- **The `db-*` and `cache-*` layers also ship single-service compose files**
+  (`docker-compose.postgres.yml`, `docker-compose.redis.yml`, …). They predate this
+  stack and bind the same host ports, so run one or the other — not both. Once this
+  stack works, those files can be deleted.