veryroundbird.house / core
forked from tangled.org/core
this repo has no description
fork atom
core / docs / spindle / openbao.md
at push-mzsvpkottnnt 2.8 kB view raw view code

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:

nix-env -iA nixpkgs.openbao

local development setup#

Start OpenBao in dev mode:

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:

export BAO_ADDR=http://localhost:8200
export BAO_TOKEN=hvs.your-root-token-here

Create the spindle KV mount:

bao secrets enable -path=spindle -version=2 kv

Set up AppRole authentication:

Create a policy file spindle-policy.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:

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:

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:

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:

bao kv list spindle/

Add a test secret via Spindle API, then check it exists:

bao kv list spindle/repos/

Get a specific secret:

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