64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
# 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 |
|