# 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

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

No errors = safe to proceed.

## Deploy

```bash
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 |