From 62dfbf99b60a255f26c784810fa70d7e30699718 Mon Sep 17 00:00:00 2001
From: Anirudh Oppiliappan <anirudh@tangled.sh>
Date: Wed, 30 Jul 2025 15:58:52 +0300
Subject: [PATCH] docs/spindle: spindle setup with openbao
Change-Id: mzsvpkottnntxwmsmrxqywzwovnoporx

Signed-off-by: Anirudh Oppiliappan <anirudh@tangled.sh>
---
 readme.md => docs/spindle/openbao.md |   0
 spindle/secrets/readme.md            | 127 +++++++++++++++++++++++++++
 2 files changed, 127 insertions(+)
 rename readme.md => docs/spindle/openbao.md (100%)
 create mode 100644 spindle/secrets/readme.md

diff --git a/readme.md b/docs/spindle/openbao.md
similarity index 100%
rename from readme.md
rename to docs/spindle/openbao.md
diff --git a/spindle/secrets/readme.md b/spindle/secrets/readme.md
new file mode 100644
index 0000000..6e5b2f8
--- /dev/null
+++ b/spindle/secrets/readme.md
@@ -0,0 +1,127 @@
+# spindle secrets with openbao
+
+This document covers setting up Spindle to use OpenBao for secrets
+management instead of the default SQLite backend.
+
+## installation
+
+Install OpenBao from nixpkgs:
+
+```bash
+nix-env -iA nixpkgs.openbao
+```
+
+## local development setup
+
+Start OpenBao in dev mode:
+
+```bash
+bao server -dev
+```
+
+This starts OpenBao on `http://localhost:8200` with a root token. Save
+the root token from the output -- you'll need it.
+
+Set up environment for bao CLI:
+
+```bash
+export BAO_ADDR=http://localhost:8200
+export BAO_TOKEN=hvs.your-root-token-here
+```
+
+Create the spindle KV mount:
+
+```bash
+bao secrets enable -path=spindle -version=2 kv
+```
+
+Set up AppRole authentication:
+
+Create a policy file `spindle-policy.hcl`:
+
+```hcl
+path "spindle/data/*" {
+  capabilities = ["create", "read", "update", "delete", "list"]
+}
+
+path "spindle/metadata/*" {
+  capabilities = ["list", "read", "delete"]
+}
+
+path "spindle/*" {
+  capabilities = ["list"]
+}
+```
+
+Apply the policy and create an AppRole:
+
+```bash
+bao policy write spindle-policy spindle-policy.hcl
+bao auth enable approle
+bao write auth/approle/role/spindle \
+    token_policies="spindle-policy" \
+    token_ttl=1h \
+    token_max_ttl=4h
+```
+
+Get the credentials:
+
+```bash
+bao read auth/approle/role/spindle/role-id
+bao write -f auth/approle/role/spindle/secret-id
+```
+
+Configure Spindle:
+
+Set these environment variables for Spindle:
+
+```bash
+export SPINDLE_SERVER_SECRETS_PROVIDER=openbao
+export SPINDLE_SERVER_SECRETS_OPENBAO_ADDR=http://localhost:8200
+export SPINDLE_SERVER_SECRETS_OPENBAO_ROLE_ID=your-role-id-from-above
+export SPINDLE_SERVER_SECRETS_OPENBAO_SECRET_ID=your-secret-id-from-above
+export SPINDLE_SERVER_SECRETS_OPENBAO_MOUNT=spindle
+```
+
+Start Spindle:
+
+Spindle will now use OpenBao for secrets storage with automatic token
+renewal.
+
+## verifying setup
+
+List all secrets:
+```bash
+bao kv list spindle/
+```
+
+Add a test secret via Spindle API, then check it exists:
+```bash
+bao kv list spindle/repos/
+```
+
+Get a specific secret:
+```bash
+bao kv get spindle/repos/your_repo_path/SECRET_NAME
+```
+
+## how it works
+
+- Secrets are stored at `spindle/repos/{sanitized_repo_path}/{secret_key}`
+- Each repository gets its own namespace
+- Repository paths like `at://did:plc:alice/myrepo` become
+  `at_did_plc_alice_myrepo`
+- The system automatically handles token renewal using AppRole
+  authentication
+- On shutdown, Spindle cleanly stops the token renewal process
+
+## troubleshooting
+
+**403 errors**: Check that your BAO_TOKEN is set and the spindle mount
+exists
+
+**404 route errors**: The spindle KV mount probably doesn't exist - run
+the mount creation step again
+
+**Token expired**: The AppRole system should handle this automatically,
+but you can check token status with `bao token lookup`
-- 
2.43.0