truenas-stacks/docs/operations/DEPLOYMENT_CHECKLIST.md

New Service Deployment Checklist

Before Adding a Service

• Determine DB requirements (postgres, mariadb, sqlite, none)
• Decide storage tier: SSD (/mnt/docker-ssd/docker/appdata/) vs tank (/mnt/tank/docker/appdata/) vs Unraid
• Check if service needs ix-databases_shared-databases network
• Check if service needs pangolin network for reverse proxy exposure

Scaffold

• Create host directories for appdata
• Set correct ownership if needed (chown or chmod 777 for permission-sensitive apps)
• Create stack folder under /mnt/docker-ssd/docker/compose/<stack>/
• Create docker-compose.yaml
• Create .env and .env.example
• If using postgres: create DB and user, or add init SQL to initdb/
• If using mariadb: add init script to initdb-mariadb/

Validate Before Deploying

cd /mnt/docker-ssd/docker/compose/<stack>
docker compose --env-file .env config

No errors = safe to proceed.

Deploy

docker compose --env-file .env up -d

After Starting

• docker ps shows container running
• docker logs <container> --tail 20 shows clean startup
• docker inspect <container> confirms mounts are correct
• Data persists after docker compose --env-file .env down && up -d

Network Checklist

If service needs shared databases:

• Top-level networks block declares ix-databases_shared-databases as external
• Service networks list includes ix-databases_shared-databases
• Verify: docker inspect <container> --format '{{json .NetworkSettings.Networks}}'

If service needs reverse proxy:

• Top-level networks block declares pangolin as external
• Service networks list includes pangolin
• Infrastructure stack (newt) must be running first

Common Failure Modes

Symptom	Likely Cause	Fix
hostname resolving error for shared-postgres	Not on ix-databases_shared-databases network	down && up not just restart
not writable errors on startup	NFS ownership mismatch	Move to SSD or chmod 777
unsupported database type	App requires config file, not just env vars	Create selfhosted.yaml or equivalent
JWT is invalid after restart	JWT secret changed	Clear browser cookies/localStorage
Port conflict on startup	Port already bound	Remove conflicting port mapping
Auto-upgrade crashes on TrueNAS	Bind mount source path missing, Docker tries to create at root	Pre-create the directory manually