# Docker Compose Stacks

This directory contains version-controlled Docker Compose files for all services in the tower-of-joy infrastructure.

## Deployment

review the http://core-api/docs openapi documentation for infrastructure management REST endpoints.

## Stack Inventory

### Phase 1: Foundation

| Stack | File | Ports | GPU | Description |
|-------|------|-------|-----|-------------|
| **Portainer** | `portainer.yml` | 8080, 8443 | No | Container management UI |
| **Nginx Proxy Manager** | `nginx-proxy-manager.yml` | 8000, 80, 443 | No | Reverse proxy and unified web interface |
| **Ollama** | `ollama.yml` | 11434 | **Yes** | ML model serving with GPU acceleration |

### Phase 2: Networking

| Stack | File | Ports | GPU | Description |
|-------|------|-------|-----|-------------|
| **Headscale** | `headscale.yml` | 8085, 9090 | No | Self-hosted Tailscale control server |

### Phase 3: Optimization

| Stack | File | Ports | GPU | Description |
|-------|------|-------|-----|-------------|
| **Watchtower** | `watchtower.yml` | - | No | Automatic container updates |
| **Duplicati** | `duplicati.yml` | 8200 | No | Backup solution |

### Backlog: Applications

| Stack | File | Ports | GPU | Description |
|-------|------|-------|-----|-------------|
| **Jellyfin** | `jellyfin.yml` | 8096, 8920, 7359, 1900 | **Yes** | Media server with GPU transcoding |
| **Nextcloud** | `nextcloud.yml` | 8082 | No | Cloud storage (includes DB and Redis) |
| **Gitea** | `gitea.yml` | 3002, 2222 | No | Git repository hosting (includes PostgreSQL) |
| **Samba** | `samba.yml` | 139, 445 | No | Network file sharing |
| **Home Assistant** | `home-assistant.yml` | 8123 | No | Smart home automation platform |

## Port Allocation

### Infrastructure Services (8000-8099)
- 8000: Nginx Proxy Manager (unified web interface)
- 8080: Portainer
- 8081: AMP (game servers - existing)
- 8082: Nextcloud
- 8085: Headscale
- 8096: Jellyfin

### Home Automation Services (8100-8199)
- 8123: Home Assistant

### Git & Development Services
- 2222: Gitea SSH
- 3002: Gitea HTTP

### Backup Services
- 8200: Duplicati

### ML/API Services (11000+)
- 11434: Ollama

### Network Services
- 80: HTTP (NPM reverse proxy)
- 443: HTTPS (NPM reverse proxy)
- 139, 445: Samba/SMB
- 9090: Headscale metrics

## Storage Convention

All stacks follow the dual-disk strategy:

**SSD (Performance):**
- Configs: `/home/jpmschweitzer/docker-data/<service>/config`
- Cache: `/home/jpmschweitzer/docker-data/<service>/cache`
- Databases: `/home/jpmschweitzer/docker-data/<service>/db`

**HDD (Capacity):**
- User content: `/mnt/media/<service>/data`
- Media files: `/mnt/media/<service>/media`
- Backups: `/mnt/media/backups/<service>`

## GPU Services

Stacks requiring GPU access (marked with **Yes** above):
- `ollama.yml` - ML model inference
- `jellyfin.yml` - Hardware transcoding

**Prerequisites:**
- NVIDIA Container Toolkit installed
- GPU verified: `docker run --rm --gpus all nvidia/cuda:11.4.0-base-ubuntu20.04 nvidia-smi`

## Before Deploying

1. **Review environment variables** - Change default passwords!
2. **Create directories** - Ensure volume paths exist
3. **Check ports** - Verify no conflicts with existing services
4. **GPU services** - Confirm NVIDIA toolkit installed
5. **Update STATUS.md** - Mark stack as deployed when complete

## After Deploying

1. **Test service** - Access web UI or API endpoint
2. **Check logs** - `docker logs <container-name>`
3. **Verify GPU** - `docker exec <container> nvidia-smi` (if applicable)
4. **Update documentation** - Add to STATUS.md and CHANGELOG.md
5. **Configure backup** - Add to Duplicati backup job

## Maintenance

### Update a Stack
```bash
# Pull latest images
docker compose -f stacks/<stack-name>.yml pull

# Recreate containers with new images
docker compose -f stacks/<stack-name>.yml up -d

# Or let Watchtower handle it automatically
```

### Backup Stack Configuration
```bash
# Stacks are version-controlled in this directory
# Backup container data separately (see scripts/backup.sh)
```

### Troubleshooting
- Container won't start: `docker logs <container-name>`
- Port conflicts: `sudo netstat -tulpn | grep <port>`
- Permission issues: Check volume path ownership
- GPU not detected: Verify NVIDIA toolkit and restart Docker

---

*For detailed implementation instructions, see containers/implementation-plan.md*