fizzlepoof/truenas-stacks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add git-crypt secrets repo setup and docs

Browse Source 
- 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
This commit is contained in:
Fizzlepoof
2026-05-12 08:15:50 -05:00
parent c30f5cc4f6
commit ae83086b06
3 changed files with 263 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/operations/SECRETS_MANAGEMENT.md
View File

@@ -2,8 +2,8 @@
## Principles
- `.env` files are gitignored and never committed to any public repo
- `.env.example` files are committed with placeholder values
- 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
@@ -25,27 +25,93 @@ All `.env` files live alongside their `docker-compose.yaml`:
/mnt/docker-ssd/docker/compose/<stack>/.env
```
## Backing Up .env Files
---
## 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
### Short term: Private Gitea repo
Create a private repo on Gitea (not GitHub) and push all .env files there:
```bash
# In a separate directory, not the main stacks repo
git init homelab-secrets
# 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
# Copy and add .env files
git remote add origin https://gitea.paccoco.com/fizzlepoof/homelab-secrets.git
git push -u origin main
git-crypt unlock /path/to/.git-crypt-secrets.key
```
### Long term: Restic + offsite
Include the compose directory (with .env files) in a restic backup:
---
## Installing git-crypt on TrueNAS (apt is blocked)
### Option 1 — one-liner (as root)
```bash
restic -r <repo> backup /mnt/docker-ssd/docker/compose --exclude="*.example"
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"
```
### Best long term: Vaultwarden
Once deployed, store each service's .env as a secure note in Vaultwarden. Single source of truth, accessible from anywhere.
### 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
@@ -62,3 +128,4 @@ Once deployed, store each service's .env as a secure note in Vaultwarden. Single
- 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