truenas-stacks/docs/operations/SECRETS_MANAGEMENT.md

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

# 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

# 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

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)

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)

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)

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:

   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