From 581eb93e21f3c771577e2913021219bf1a692446 Mon Sep 17 00:00:00 2001
From: Jackie Xu <jackie@jackiexu.com>
Date: Thu, 30 Apr 2026 13:58:55 +0200
Subject: [PATCH] chore: add docker compose for local test infra

---
 .github/workflows/e2e.yml  |  2 +-
 .github/workflows/test.yml |  2 +-
 README.md                  | 12 ++++++++++++
 docker-compose.test.yml    | 24 ++++++++++++++++++++++++
 package.json               |  2 ++
 5 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 docker-compose.test.yml

diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
index 9093fd32fe..a86bbcd755 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/e2e.yml
@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-22.04
     services:
       postgres:
-        image: postgres:12.1-alpine
+        image: postgres:17-alpine
         ports:
           - 5432:5432
         # needed because the postgres container does not provide a healthcheck
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 9a447b9b98..429f3a0841 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-22.04
     services:
       postgres:
-        image: postgres:12.1-alpine
+        image: postgres:17-alpine
         ports:
           - 5432:5432
         # needed because the postgres container does not provide a healthcheck
diff --git a/README.md b/README.md
index 62ca0e8a17..8ccb04f5be 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,18 @@ We'd love your support in improving MUD, [see here for instructions](https://mud
 This monorepo includes all of MUD's source code, and pull requests are always welcome.
 To discuss new features or changes [join our Discord](https://lattice.xyz/discord).
 
+### Running tests locally
+
+Some test suites (`store-sync`, KMS account tests) need a Postgres instance and `local-kms`. Bring them up with Docker:
+
+```
+pnpm test:setup
+AWS_ENDPOINT_URL='http://localhost:8080' pnpm test:ci
+pnpm test:teardown
+```
+
+Anvil is started automatically by the `with-anvil` wrapper used by `pnpm test` and `pnpm test:ci`.
+
 ## Community support
 
 [Join our Discord](https://lattice.xyz/discord) to get support and connect with the community!
diff --git a/docker-compose.test.yml b/docker-compose.test.yml
new file mode 100644
index 0000000000..cd3cc8fc24
--- /dev/null
+++ b/docker-compose.test.yml
@@ -0,0 +1,24 @@
+services:
+  postgres:
+    image: postgres:17-alpine
+    ports:
+      - "127.0.0.1:5432:5432"
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_DB: postgres
+      POSTGRES_HOST_AUTH_METHOD: trust
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  local-kms:
+    image: nsmithuk/local-kms:3.12.0
+    ports:
+      - "127.0.0.1:8080:8080"
+    healthcheck:
+      test: ["CMD-SHELL", "nc -z localhost 8080"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
diff --git a/package.json b/package.json
index af2cd1d3f4..8fc6563c63 100644
--- a/package.json
+++ b/package.json
@@ -28,6 +28,8 @@
     "release:version": "changeset version && pnpm install --lockfile-only && pnpm run changelog:generate",
     "test": "with-anvil turbo run test --concurrency=100%",
     "test:ci": "with-anvil turbo run test:ci --concurrency=100%",
+    "test:setup": "docker compose -f docker-compose.test.yml up -d --wait",
+    "test:teardown": "docker compose -f docker-compose.test.yml down",
     "type-bench": "pnpm --filter ./test/ts-benchmarks bench",
     "type-stats-repo": "attest stats packages/*",
     "vercel:prepare": "ln -sf /vercel/.foundry/bin/* node_modules/.bin/ && forge --version"