2e0bd6d49a
- scripts/setup-secrets-repo.sh: replace dpkg-deb install with Docker method - dev/docker-compose.yaml: add git-crypt-init service (profile: setup) - docs/operations/SECRETS_MANAGEMENT.md: document git-crypt encrypted repo, unlock procedure, rebuild runbook, and TrueNAS install methods
132 lines
3.6 KiB
Markdown
132 lines
3.6 KiB
Markdown
# Secrets Management
|
|
|
|
## Principles
|
|
- `.env` files are gitignored and never committed to any public repo
|
|
- Real `.env` files live only on the host at the stack directory
|
|
- `.env.example` files are committed with placeholder values
|
|
- Secrets are generated with standard tools, never reused across services
|
|
|
|
## Generating Secrets
|
|
|
|
```bash
|
|
# Database passwords
|
|
openssl rand -hex 24
|
|
|
|
# JWT / session secrets
|
|
openssl rand -hex 32
|
|
|
|
# API keys (where format allows)
|
|
openssl rand -base64 32
|
|
```
|
|
|
|
## .env File Locations
|
|
All `.env` files live alongside their `docker-compose.yaml`:
|
|
```
|
|
/mnt/docker-ssd/docker/compose/<stack>/.env
|
|
```
|
|
|
|
---
|
|
|
|
## Secrets Repo (git-crypt)
|
|
|
|
All secrets are backed up to a **private, git-crypt encrypted** Gitea repo:
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Repo** | `https://gitea.paccoco.com/fizzlepoof/homelab-secrets` (private) |
|
|
| **Local path** | `/mnt/docker-ssd/docker/secrets/` |
|
|
| **Symmetric key** | `/root/.git-crypt-secrets.key` on PD |
|
|
| **Key backup** | Password manager / USB — **do not lose this** |
|
|
|
|
### Directory structure
|
|
|
|
| Directory | Contents |
|
|
|-----------|----------|
|
|
| `env/` | `.env` files for each stack |
|
|
| `keys/` | API keys and tokens |
|
|
| `certs/` | TLS certificates |
|
|
| `tokens/` | Service tokens (Paperless, LiteLLM, etc.) |
|
|
| `ssh/` | SSH private keys |
|
|
|
|
### Adding a secret
|
|
|
|
```bash
|
|
# As root on PD:
|
|
cp /mnt/docker-ssd/docker/compose/ai/.env /mnt/docker-ssd/docker/secrets/env/ai.env
|
|
cd /mnt/docker-ssd/docker/secrets
|
|
git add -A
|
|
git -c user.name="Fizzlepoof" -c user.email="admin@paccoco.com" commit -m "chore: add ai stack env"
|
|
git push
|
|
```
|
|
|
|
Files are encrypted automatically by git-crypt on push — no extra steps needed.
|
|
|
|
### Unlocking on a new machine
|
|
|
|
```bash
|
|
git clone https://gitea.paccoco.com/fizzlepoof/homelab-secrets
|
|
cd homelab-secrets
|
|
git-crypt unlock /path/to/.git-crypt-secrets.key
|
|
```
|
|
|
|
---
|
|
|
|
## Installing git-crypt on TrueNAS (apt is blocked)
|
|
|
|
### Option 1 — one-liner (as root)
|
|
```bash
|
|
docker run --rm -v /tmp:/out debian:bookworm-slim \
|
|
bash -c "apt-get update -qq && apt-get install -y -qq git-crypt && cp /usr/bin/git-crypt /out/git-crypt"
|
|
mkdir -p /root/bin && cp /tmp/git-crypt /root/bin/git-crypt && chmod +x /root/bin/git-crypt
|
|
export PATH="/root/bin:$PATH"
|
|
```
|
|
|
|
### Option 2 — via Gitea stack compose (recommended for rebuilds)
|
|
```bash
|
|
cd /mnt/docker-ssd/docker/compose/dev
|
|
docker compose --profile setup up git-crypt-init
|
|
export PATH="/root/bin:$PATH"
|
|
```
|
|
|
|
The `git-crypt-init` service in `dev/docker-compose.yaml` handles the install automatically.
|
|
|
|
### Make PATH persistent (add to /root/.bashrc)
|
|
```bash
|
|
echo 'export PATH="/root/bin:$PATH"' >> /root/.bashrc
|
|
```
|
|
|
|
---
|
|
|
|
## Full Rebuild Runbook
|
|
|
|
On a fresh PD:
|
|
|
|
1. Install git-crypt (Option 1 or 2 above)
|
|
2. Clone and unlock the secrets repo:
|
|
```bash
|
|
git clone https://gitea.paccoco.com/fizzlepoof/homelab-secrets /mnt/docker-ssd/docker/secrets
|
|
cd /mnt/docker-ssd/docker/secrets
|
|
git-crypt unlock /path/to/.git-crypt-secrets.key
|
|
```
|
|
3. Copy `.env` files back into their stack directories from `secrets/env/`
|
|
4. Redeploy stacks
|
|
|
|
---
|
|
|
|
## Known Credentials Locations
|
|
|
|
| Service | Where stored |
|
|
|---------|-------------|
|
|
| shared-postgres | `databases/.env` |
|
|
| shared-mariadb | `databases/.env` |
|
|
| OpenWebUI DB | `ai/.env` — user: openwebui, db: openwebui |
|
|
| Donetick | `home/.env` + `selfhosted.yaml` |
|
|
| Meshmonitor | `meshtastic/.env` |
|
|
| Gitea | `dev/.env` |
|
|
|
|
## Security Reminders
|
|
- Regenerate Wings token on N.O.M.A.D. (was exposed in chat — TODO)
|
|
- Regenerate N.O.M.A.D. Newt secret (was exposed in chat — TODO)
|
|
- Disable signups in OpenWebUI after creating initial account
|
|
- Back up `/root/.git-crypt-secrets.key` to password manager
|