veryroundbird.house
1# spindle secrets with openbao
2
3This document covers setting up Spindle to use OpenBao for secrets
4management instead of the default SQLite backend.
5
6## installation
7
8Install OpenBao from nixpkgs:
9
10```bash
11nix-env -iA nixpkgs.openbao
12```
13
14## local development setup
15
16Start OpenBao in dev mode:
17
18```bash
19bao server -dev
20```
21
22This starts OpenBao on `http://localhost:8200` with a root token. Save
23the root token from the output -- you'll need it.
24
25Set up environment for bao CLI:
26
27```bash
28export BAO_ADDR=http://localhost:8200
29export BAO_TOKEN=hvs.your-root-token-here
30```
31
32Create the spindle KV mount:
33
34```bash
35bao secrets enable -path=spindle -version=2 kv
36```
37
38Set up AppRole authentication:
39
40Create a policy file `spindle-policy.hcl`:
41
42```hcl
43path "spindle/data/*" {
44 capabilities = ["create", "read", "update", "delete", "list"]
45}
46
47path "spindle/metadata/*" {
48 capabilities = ["list", "read", "delete"]
49}
50
51path "spindle/*" {
52 capabilities = ["list"]
53}
54```
55
56Apply the policy and create an AppRole:
57
58```bash
59bao policy write spindle-policy spindle-policy.hcl
60bao auth enable approle
61bao write auth/approle/role/spindle \
62 token_policies="spindle-policy" \
63 token_ttl=1h \
64 token_max_ttl=4h
65```
66
67Get the credentials:
68
69```bash
70bao read auth/approle/role/spindle/role-id
71bao write -f auth/approle/role/spindle/secret-id
72```
73
74Configure Spindle:
75
76Set these environment variables for Spindle:
77
78```bash
79export SPINDLE_SERVER_SECRETS_PROVIDER=openbao
80export SPINDLE_SERVER_SECRETS_OPENBAO_ADDR=http://localhost:8200
81export SPINDLE_SERVER_SECRETS_OPENBAO_ROLE_ID=your-role-id-from-above
82export SPINDLE_SERVER_SECRETS_OPENBAO_SECRET_ID=your-secret-id-from-above
83export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle
84```
85
86Start Spindle:
87
88Spindle will now use OpenBao for secrets storage with automatic token
89renewal.
90
91## verifying setup
92
93List all secrets:
94
95```bash
96bao kv list spindle/
97```
98
99Add a test secret via Spindle API, then check it exists:
100
101```bash
102bao kv list spindle/repos/
103```
104
105Get a specific secret:
106
107```bash
108bao kv get spindle/repos/your_repo_path/SECRET_NAME
109```
110
111## how it works
112
113- Secrets are stored at `spindle/repos/{sanitized_repo_path}/{secret_key}`
114- Each repository gets its own namespace
115- Repository paths like `at://did:plc:alice/myrepo` become
116 `at_did_plc_alice_myrepo`
117- The system automatically handles token renewal using AppRole
118 authentication
119- On shutdown, Spindle cleanly stops the token renewal process
120
121## troubleshooting
122
123**403 errors**: Check that your BAO_TOKEN is set and the spindle mount
124exists
125
126**404 route errors**: The spindle KV mount probably doesn't exist - run
127the mount creation step again
128
129**Token expired**: The AppRole system should handle this automatically,
130but you can check token status with `bao token lookup`