pdewey.com
forked from
tangled.org/core
fork
Configure Feed
Select the types of activity you want to include in your feed.
Monorepo for Tangled
fork
Configure Feed
Select the types of activity you want to include in your feed.
docs/spindle: spindle setup with openbao
Signed-off-by: Anirudh Oppiliappan <anirudh@tangled.sh>
authored by
Tangled
2328f177
17a5cd87
+130
+130
docs/spindle/openbao.md
+130
docs/spindle/openbao.md
···
1
+
# spindle secrets with openbao
2
+
3
+
This document covers setting up Spindle to use OpenBao for secrets
4
+
management instead of the default SQLite backend.
5
+
6
+
## installation
7
+
8
+
Install OpenBao from nixpkgs:
9
+
10
+
```bash
11
+
nix-env -iA nixpkgs.openbao
12
+
```
13
+
14
+
## local development setup
15
+
16
+
Start OpenBao in dev mode:
17
+
18
+
```bash
19
+
bao server -dev
20
+
```
21
+
22
+
This starts OpenBao on `http://localhost:8200` with a root token. Save
23
+
the root token from the output -- you'll need it.
24
+
25
+
Set up environment for bao CLI:
26
+
27
+
```bash
28
+
export BAO_ADDR=http://localhost:8200
29
+
export BAO_TOKEN=hvs.your-root-token-here
30
+
```
31
+
32
+
Create the spindle KV mount:
33
+
34
+
```bash
35
+
bao secrets enable -path=spindle -version=2 kv
36
+
```
37
+
38
+
Set up AppRole authentication:
39
+
40
+
Create a policy file `spindle-policy.hcl`:
41
+
42
+
```hcl
43
+
path "spindle/data/*" {
44
+
capabilities = ["create", "read", "update", "delete", "list"]
45
+
}
46
+
47
+
path "spindle/metadata/*" {
48
+
capabilities = ["list", "read", "delete"]
49
+
}
50
+
51
+
path "spindle/*" {
52
+
capabilities = ["list"]
53
+
}
54
+
```
55
+
56
+
Apply the policy and create an AppRole:
57
+
58
+
```bash
59
+
bao policy write spindle-policy spindle-policy.hcl
60
+
bao auth enable approle
61
+
bao write auth/approle/role/spindle \
62
+
token_policies="spindle-policy" \
63
+
token_ttl=1h \
64
+
token_max_ttl=4h
65
+
```
66
+
67
+
Get the credentials:
68
+
69
+
```bash
70
+
bao read auth/approle/role/spindle/role-id
71
+
bao write -f auth/approle/role/spindle/secret-id
72
+
```
73
+
74
+
Configure Spindle:
75
+
76
+
Set these environment variables for Spindle:
77
+
78
+
```bash
79
+
export SPINDLE_SERVER_SECRETS_PROVIDER=openbao
80
+
export SPINDLE_SERVER_SECRETS_OPENBAO_ADDR=http://localhost:8200
81
+
export SPINDLE_SERVER_SECRETS_OPENBAO_ROLE_ID=your-role-id-from-above
82
+
export SPINDLE_SERVER_SECRETS_OPENBAO_SECRET_ID=your-secret-id-from-above
83
+
export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle
84
+
```
85
+
86
+
Start Spindle:
87
+
88
+
Spindle will now use OpenBao for secrets storage with automatic token
89
+
renewal.
90
+
91
+
## verifying setup
92
+
93
+
List all secrets:
94
+
95
+
```bash
96
+
bao kv list spindle/
97
+
```
98
+
99
+
Add a test secret via Spindle API, then check it exists:
100
+
101
+
```bash
102
+
bao kv list spindle/repos/
103
+
```
104
+
105
+
Get a specific secret:
106
+
107
+
```bash
108
+
bao 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
124
+
exists
125
+
126
+
**404 route errors**: The spindle KV mount probably doesn't exist - run
127
+
the mount creation step again
128
+
129
+
**Token expired**: The AppRole system should handle this automatically,
130
+
but you can check token status with `bao token lookup`