From abdb195c8e74c99eef20a51798bd70aa3f3fae12 Mon Sep 17 00:00:00 2001 From: Rongsong Shen Date: Fri, 29 May 2026 10:34:41 +0000 Subject: [PATCH] docs(ha-config-bootstrap): add TLS cert setup instructions to manual test guide --- .../specs/ha-config-bootstrap/manual-tests.md | 30 ++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/.kiro/specs/ha-config-bootstrap/manual-tests.md b/.kiro/specs/ha-config-bootstrap/manual-tests.md index 690d1aa8..b38efad6 100644 --- a/.kiro/specs/ha-config-bootstrap/manual-tests.md +++ b/.kiro/specs/ha-config-bootstrap/manual-tests.md @@ -46,14 +46,42 @@ All tests use temporary work directories. Each controller node needs: - Shared `--peers` list (comma-separated `name=host:port`, priority order 0 = highest) - A `--workdir` for persistent state (`ha-term.bin`, `data/wal/`, `data/snap/`) - A `--logfile` so you can capture output +- **TLS certificates** at `{workdir}/certs/xce.crt` and `{workdir}/certs/xce.key` — the + controller reads them automatically from that fixed path (no CLI flag) ```bash # One-time setup -mkdir -p /tmp/xce-a /tmp/xce-b /tmp/xce-a/data /tmp/xce-b/data +mkdir -p /tmp/xce-a/certs /tmp/xce-b/certs /tmp/xce-a/data /tmp/xce-b/data BINARY=/home/rshen/projects/xce/worktrees/persistent_ha/src/xce.build/controller/xce_controller PEERS="ctrl-a=127.0.0.1:9901,ctrl-b=127.0.0.1:9902" ``` +### TLS Certificate Setup (required) + +The controller expects `{workdir}/certs/xce.crt` (certificate) and +`{workdir}/certs/xce.key` (private key). For local testing, generate a +self-signed cert shared by both nodes: + +```bash +# Generate a self-signed cert (valid 10 years, localhost + 127.0.0.1 SANs) +openssl req -x509 -newkey rsa:2048 -nodes \ + -keyout /tmp/xce.key \ + -out /tmp/xce.crt \ + -days 3650 \ + -subj "/CN=xce-controller" \ + -addext "subjectAltName=IP:127.0.0.1,DNS:localhost" + +# Copy to both node work dirs +cp /tmp/xce.crt /tmp/xce-a/certs/xce.crt +cp /tmp/xce.key /tmp/xce-a/certs/xce.key +cp /tmp/xce.crt /tmp/xce-b/certs/xce.crt +cp /tmp/xce.key /tmp/xce-b/certs/xce.key +``` + +> **Note:** Both nodes must trust each other's certificate. Using the same +> self-signed cert for all nodes (same CA = same cert) is the simplest setup for +> local testing. In production each node has its own cert signed by a shared CA. + **Start Node A (Terminal 1):** ```bash $BINARY \