configuration for self hosting a spindle in docker
1# CLAUDE.md
2
3This file provides guidance to Claude Code when working with code in this repository.
4
5## What this repo is
6
7A Docker Compose deployment stack for [Spindle](https://tangled.org) (a CI/CD pipeline tool) backed by [OpenBao](https://openbao.org) (an open-source HashiCorp Vault fork) for secrets management. Spindle is not developed here — it is cloned from `tangled.org/tangled.org/core` at tag `v1.13.0-alpha` and built inside `Dockerfile`.
8
9## Current state
10
11This stack is actively being tested for first-time deployment on Ubuntu Linux. The init script and Docker config have had several fixes applied and may need further iteration.
12
13Known working:
14- OpenBao starts and reads config correctly
15- `init-openbao.sh` fixes data volume permissions, restarts OpenBao, and runs the full vault bootstrap
16
17Known issues / things being tested:
18- Full end-to-end stack (openbao → openbao-proxy → spindle) not yet verified
19- Spindle healthcheck is intentionally omitted pending manual testing of its HTTP endpoints
20
21## Architecture
22
23```
24┌──────────┐ AppRole ┌───────────────┐ KV v2 ┌─────────┐
25│ spindle │ ─────────────► │ openbao-proxy │ ─────────────► │ openbao │
26│ :6555 │ │ :8201 │ │ :8200 │
27└──────────┘ └───────────────┘ └─────────┘
28 │
29 │ /var/run/docker.sock
30 ▼
31 Host Docker daemon (pipeline containers run here)
32```
33
34- **openbao** — vault backend, file storage, sealed on every start
35- **openbao-proxy** — AppRole sidecar, auto-authenticates, token cached at `/tmp/openbao-token`
36- **spindle** — CI runner, starts only after proxy is healthy, mounts Docker socket
37
38## Key config files
39
40| File | Purpose |
41|------|---------|
42| `docker-compose.yml` | Service definitions, volumes, port bindings, dependency order |
43| `Dockerfile` | Clones `tangled.org/core` at `v1.13.0-alpha`, builds with Go, produces Alpine image |
44| `config/openbao/server/server.hcl` | OpenBao server (file storage, TCP listener on 8200, TLS off) |
45| `config/openbao/proxy/proxy.hcl` | Proxy AppRole auto-auth, token sink at `/tmp/openbao-token`, listener on 8201 |
46| `config/openbao/spindle-policy.hcl` | Grants Spindle KV v2 CRUD on `spindle/data/*` and `spindle/metadata/*` |
47| `init-openbao.sh` | One-time bootstrap: fixes volume perms, inits vault, enables KV v2, creates AppRole |
48| `.env.sample` | All configurable env vars with defaults — copy to `.env` before starting |
49
50## Important implementation details
51
52- Config directories are split: `config/openbao/server/` and `config/openbao/proxy/` are mounted separately so each service only sees its own HCL files. Mixing them caused OpenBao server to fail parsing proxy-specific stanzas.
53- The `openbao-data` Docker volume is created root-owned by default. `init-openbao.sh` fixes this with `docker compose exec --user root openbao chown -R openbao:openbao /openbao/data` before running init.
54- All `docker compose exec` calls in the init script use `-T` with `</dev/null` to prevent stdin hanging.
55- OpenBao port 8200 is bound to `127.0.0.1` only (not exposed to the network).
56- Both OpenBao and its proxy have `IPC_LOCK` capability to prevent secrets swapping to disk.
57- All images are pinned to SHA256 digests. Spindle source is pinned to commit `3572988b89fa093269ae78e02d7283ee206b6888`.
58
59## First-time setup
60
61```bash
62cp .env.sample .env
63# Set SPINDLE_SERVER_HOSTNAME and SPINDLE_SERVER_OWNER in .env
64
65docker compose up -d openbao
66# Wait for "seal configuration missing, not initialized" in logs, then:
67
68./init-openbao.sh # ONE-TIME ONLY — save the unseal key and root token it prints
69
70docker compose up -d
71```
72
73## After every restart
74
75OpenBao seals itself on restart. Unseal before the proxy or Spindle can start:
76
77```bash
78docker compose exec openbao bao operator unseal -address=http://localhost:8200 <unseal_key>
79```
80
81## Verify the stack
82
83```bash
84curl http://localhost:8200/v1/sys/health # OpenBao server (127.0.0.1 only)
85curl http://localhost:6555/ # Spindle
86```