compose-files/secrets

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.

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.

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	⏳	⏳	⏳
unifi	✅ N/A (no secrets)	✅ N/A	⏳
vaultwarden	⏳	⏳	⏳
woodpecker	⏳ Manual only	⏳ N/A	⏳