111 lines
4.2 KiB
Markdown
111 lines
4.2 KiB
Markdown
# Secrets Management
|
|
|
|
This directory documents the secrets required for each Docker Swarm stack.
|
|
|
|
## How It Works
|
|
|
|
```
|
|
Secret values live in Woodpecker (encrypted)
|
|
→ pipeline reads them at deploy time
|
|
Docker Swarm secret store (encrypted Raft DB, replicated across all nodes)
|
|
→ mounted into containers at runtime
|
|
/run/secrets/<secret_name>
|
|
```
|
|
|
|
## Files in This Directory
|
|
|
|
Each `<stack>.secrets.example` file documents:
|
|
- **Which keys are secrets** (sensitive — must go in Woodpecker)
|
|
- **Which keys are non-secrets** (config values — can live in compose file or .env)
|
|
- **The Woodpecker secret name** to use for each value
|
|
- **What the value is used for**
|
|
|
|
These files contain **NO actual values** — they are safe to commit to Git.
|
|
|
|
## How to Add a Secret to Woodpecker
|
|
|
|
1. Go to **https://woodpecker.bryanmail.net**
|
|
2. Navigate to `homelab/compose-files` → **Settings** → **Secrets**
|
|
3. Click **Add Secret**
|
|
4. Set the **Name** exactly as shown in the `.secrets.example` file
|
|
5. Paste the **Value** from the corresponding `.env` file on the host
|
|
6. Save
|
|
|
|
## How to Migrate a Stack
|
|
|
|
### Step 1 — Add secrets to Woodpecker UI
|
|
Use the stack's `.secrets.example` file as your checklist.
|
|
|
|
### Step 2 — Add the stack's case to `.woodpecker.yml`
|
|
In the `provision-secrets` step, add a case for the stack that calls
|
|
`create_or_update_secret` for each secret. (Or, preferred for new
|
|
migrations: add an entry to `secrets/secrets-map.yaml` + a
|
|
`<stack>.env.template` and call `deploy/provision-stack.py <stack>`
|
|
instead — see the `ai` and `traefik` entries for the current pattern.)
|
|
|
|
### Step 3 — Test by pushing a trivial change to the stack's yaml file
|
|
Watch the pipeline run: provision-secrets → validate → deploy → verify → notify.
|
|
|
|
### Step 4 — Remove the `.env` file from the host (optional)
|
|
Once the pipeline is managing secrets, the host-side `.env` file is redundant.
|
|
Keep it as a backup until you're confident.
|
|
|
|
## Secret Naming Convention
|
|
|
|
Docker secret names use underscores and lowercase. The convention used here is:
|
|
```
|
|
<stack>_<variable_purpose>
|
|
```
|
|
Examples:
|
|
- `git_db_password`
|
|
- `ai_aws_secret_access_key`
|
|
- `security_crowdsec_api_key`
|
|
|
|
## Important Notes
|
|
|
|
- **Docker cannot update a secret in-place.** The `deploy/create-secrets.sh`
|
|
helper handles this by removing and recreating changed secrets automatically.
|
|
Services using the secret will continue running with the old value until the
|
|
stack is redeployed.
|
|
|
|
- **Woodpecker cannot manage its own secrets.** The `woodpecker` stack must
|
|
always be managed manually. See `woodpecker.secrets.example` for details.
|
|
|
|
- **PostgreSQL is highest risk.** Its master password is used by nearly every
|
|
other stack. Migrate it last.
|
|
|
|
- **Never commit a rendered env file, even by accident.** `traefik/traefik.env`
|
|
was committed to git for a period (discovered/fixed 2026-09-12) with a
|
|
literal "***REDACTED***" placeholder as KEEPALIVED_PASSWORD, which was
|
|
silently restored every time the file was deleted or the checkout resynced
|
|
from git — causing a real VRRP auth outage. `.gitignore` blanket-excludes
|
|
`*.env`, but that rule does NOT retroactively untrack a file already
|
|
committed before the rule existed. If you ever see a stack's `.env` file
|
|
show up in `git status` as tracked, stop and untrack it (`git rm --cached`)
|
|
before doing anything else.
|
|
|
|
## Migration Status
|
|
|
|
| Stack | Secrets in Woodpecker | Pipeline Step Added | .env Removed |
|
|
|-------|------------------------|----------------------|---------------|
|
|
| 3dprint | ⏳ | ⏳ | ⏳ |
|
|
| ai | ⏳ | ⏳ | ⏳ |
|
|
| auth | ⏳ | ⏳ | ⏳ |
|
|
| entertainment | ⏳ | ⏳ | ⏳ |
|
|
| gamma | ⏳ | ⏳ | ⏳ |
|
|
| git | ⏳ | ⏳ | ⏳ |
|
|
| guacamole | ⏳ | ⏳ | ⏳ |
|
|
| homeassistant | ⏳ | ⏳ | ⏳ |
|
|
| maintenance | ✅ N/A (no secrets) | ✅ N/A | ⏳ |
|
|
| media | ✅ N/A (no secrets) | ✅ N/A | ⏳ |
|
|
| mealie | ⏳ | ⏳ | ⏳ |
|
|
| meshcentral | ⏳ | ⏳ | ⏳ |
|
|
| n8n | ⏳ | ⏳ | ⏳ |
|
|
| postgresql | ⏳ | ⏳ | ⏳ |
|
|
| productivity | ⏳ | ⏳ | ⏳ |
|
|
| security | ⏳ | ⏳ | ⏳ |
|
|
| traefik | ✅ (manifest-driven, 2026-09-12) | ✅ (manifest-driven, 2026-09-12) | ⏳ |
|
|
| unifi | ✅ N/A (no secrets) | ✅ N/A | ⏳ |
|
|
| vaultwarden | ⏳ | ⏳ | ⏳ |
|
|
| woodpecker | ⏳ Manual only | ⏳ N/A | ⏳ |
|