From 29fa443b937c5e53a20deac2afdeb2be61b00828 Mon Sep 17 00:00:00 2001
From: Halit Aksoy <jhalitaksoy@gmail.com>
Date: Fri, 16 Oct 2026 00:05:21 +0300
Subject: [PATCH] build: add shared Postgres and Valkey to compose

- postgres replaces keycloak-db and holds a keycloak and a mancala database,
  each with its own user, created by apps/postgres/init
- valkey with an append-only file for live game state and caches
- backend gets DATABASE_URL and VALKEY_URL
---
 README.md                          | 17 +++++++++++++
 apps/compose.yaml                  | 41 +++++++++++++++++++++++-------
 apps/keycloak/README.md            |  5 ++++
 apps/postgres/init/01-databases.sh | 15 +++++++++++
 docs/specs/game-history/tasks.md   |  2 +-
 5 files changed, 70 insertions(+), 10 deletions(-)
 create mode 100755 apps/postgres/init/01-databases.sh

diff --git a/README.md b/README.md
index 545cd3d..6d1c657 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,23 @@ yarn build:packages        # from the repo root
 
 After changing a package, rebuild it (or run `yarn dev` in it to rebuild on change); the apps pick up the new `dist`.
 
+Postgres (games and Keycloak), Valkey (live games and caches) and Keycloak run with Docker Compose. Create
+`apps/.env` once, then start them:
+
+```sh
+cd apps
+cat > .env <<EOF
+POSTGRES_PASSWORD=postgres
+KEYCLOAK_DB_PASSWORD=keycloak
+KEYCLOAK_ADMIN_PASSWORD=admin
+MANCALA_DB_PASSWORD=mancala
+EOF
+docker compose up -d --build postgres valkey keycloak
+```
+
+Postgres is on `localhost:5433` and Valkey on `localhost:6379`; the backend's defaults point there. Then run
+`yarn dev` in `apps/backend` (port 5005) and in `apps/frontend` (port 1234).
+
 Docker images for the backend and frontend are built from the repo root:
 
 ```sh
diff --git a/apps/compose.yaml b/apps/compose.yaml
index 39e9a41..f9fbc60 100644
--- a/apps/compose.yaml
+++ b/apps/compose.yaml
@@ -11,8 +11,13 @@ services:
       KEYCLOAK_JWKS_URL: http://keycloak:8080/realms/mancala/protocol/openid-connect/certs
       KEYCLOAK_CLIENT_IDS: mancala-web
       LEGACY_USERKEY_AUTH: ${LEGACY_USERKEY_AUTH:-true}
+      DATABASE_URL: postgres://mancala:${MANCALA_DB_PASSWORD}@postgres:5432/mancala
+      VALKEY_URL: redis://valkey:6379
     ports:
       - "5000:6000"
+    depends_on:
+      - postgres
+      - valkey
   frontend:
     image: jhalitaksoy/mancala-frontend:latest
     build:
@@ -22,16 +27,33 @@ services:
         KEYCLOAK_URL: ${KEYCLOAK_HOSTNAME:-http://localhost:8080}
     ports:
       - "3000:3000"
-  keycloak-db:
+  # Shared by Keycloak and the game, each with its own database and user (see postgres/init).
+  postgres:
     image: postgres:17.6
     environment:
-      POSTGRES_DB: keycloak
-      POSTGRES_USER: keycloak
-      POSTGRES_PASSWORD: ${KEYCLOAK_DB_PASSWORD:?set KEYCLOAK_DB_PASSWORD in apps/.env}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in apps/.env}
+      KEYCLOAK_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD:?set KEYCLOAK_DB_PASSWORD in apps/.env}
+      MANCALA_DB_PASSWORD: ${MANCALA_DB_PASSWORD:?set MANCALA_DB_PASSWORD in apps/.env}
     volumes:
-      - keycloak-db:/var/lib/postgresql/data
+      - postgres-data:/var/lib/postgresql/data
+      - ./postgres/init:/docker-entrypoint-initdb.d:ro
+    ports:
+      - "127.0.0.1:5433:5432"
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"]
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+  # Live game state and caches; the append-only file keeps live games across restarts.
+  valkey:
+    image: valkey/valkey:9.1.2
+    command: ["valkey-server", "--appendonly", "yes"]
+    volumes:
+      - valkey-data:/data
+    ports:
+      - "127.0.0.1:6379:6379"
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
       interval: 5s
       timeout: 5s
       retries: 10
@@ -39,7 +61,7 @@ services:
     image: jhalitaksoy/mancala-keycloak:latest
     build: ./keycloak
     environment:
-      KC_DB_URL: jdbc:postgresql://keycloak-db:5432/keycloak
+      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
       KC_DB_USERNAME: keycloak
       KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD}
       # Public URL of Keycloak; https://auth.playmancala.app in production
@@ -52,8 +74,9 @@ services:
     ports:
       - "127.0.0.1:8080:8080"
     depends_on:
-      keycloak-db:
+      postgres:
         condition: service_healthy
 
 volumes:
-  keycloak-db:
+  postgres-data:
+  valkey-data:
diff --git a/apps/keycloak/README.md b/apps/keycloak/README.md
index b4377e2..b0a5c21 100644
--- a/apps/keycloak/README.md
+++ b/apps/keycloak/README.md
@@ -38,12 +38,17 @@ console too, or delete the realm and restart Keycloak.
 ```sh
 cd apps
 cat > .env <<EOF
+POSTGRES_PASSWORD=change-me
 KEYCLOAK_DB_PASSWORD=change-me
 KEYCLOAK_ADMIN_PASSWORD=change-me
+MANCALA_DB_PASSWORD=change-me
 EOF
 docker compose up -d --build keycloak
 ```
 
+Keycloak uses the `keycloak` database of the shared `postgres` service; `apps/postgres/init` creates it the first time
+the Postgres volume is initialised.
+
 Keycloak is then at http://localhost:8080 and the admin console at http://localhost:8080/admin.
 In production set `KEYCLOAK_HOSTNAME=https://auth.playmancala.app`; nginx proxies that host to port 8080.
 
diff --git a/apps/postgres/init/01-databases.sh b/apps/postgres/init/01-databases.sh
new file mode 100755
index 0000000..0807b53
--- /dev/null
+++ b/apps/postgres/init/01-databases.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# Runs once, when the Postgres data directory is created: one database and user each for Keycloak and the game.
+set -euo pipefail
+
+: "${KEYCLOAK_DB_PASSWORD:?KEYCLOAK_DB_PASSWORD is not set}"
+: "${MANCALA_DB_PASSWORD:?MANCALA_DB_PASSWORD is not set}"
+
+psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" \
+    -v keycloak_password="$KEYCLOAK_DB_PASSWORD" \
+    -v mancala_password="$MANCALA_DB_PASSWORD" <<'EOSQL'
+CREATE ROLE keycloak LOGIN PASSWORD :'keycloak_password';
+CREATE DATABASE keycloak OWNER keycloak;
+CREATE ROLE mancala LOGIN PASSWORD :'mancala_password';
+CREATE DATABASE mancala OWNER mancala;
+EOSQL
diff --git a/docs/specs/game-history/tasks.md b/docs/specs/game-history/tasks.md
index df47b81..eab1633 100644
--- a/docs/specs/game-history/tasks.md
+++ b/docs/specs/game-history/tasks.md
@@ -2,7 +2,7 @@
 
 Work through the tasks in order; each ends with its tests passing and a commit. Tick a task when it is committed.
 
-- [ ] 1. **Infrastructure**: `postgres` service with init script for the `keycloak` and `mancala` databases
+- [x] 1. **Infrastructure**: `postgres` service with init script for the `keycloak` and `mancala` databases
       (replacing `keycloak-db`), `valkey` service, backend `DATABASE_URL` / `VALKEY_URL`, `.env` variables, README.
 - [ ] 2. **Core types and history helpers**: `PlayerSummary`, `MoveRecord`, summaries, `GameRecord`,
       `TURN_TIMEOUT_MS`, new channels, `offlineSince`; `getInitialBoard`, `getBoardAfterMove`, `describeMove`,