portainer-core/docs/reference/stacks.md

# Docker Compose Stacks Reference

Complete reference for all Docker Compose stacks in the portainer-core infrastructure.

## Deployment

See the [core-api OpenAPI documentation](http://localhost:8083/docs) for infrastructure management REST endpoints.

All stacks are located in the `/stacks/` directory and version-controlled.

## 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: Monitoring

| Stack | File | Ports | GPU | Description |
|-------|------|-------|-----|-------------|
| **Uptime Kuma** | `uptime-kuma.yml` | 3001 | No | Service availability monitoring |
| **Netdata** | `netdata.yml` | 19999 | No | Real-time system performance monitoring |
| **Heimdall** | `heimdall.yml` | 8888, 8889 | No | Application dashboard |

### Phase 4: Optimization

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

### 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 (uses shared PostgreSQL and Redis) |
| **Gitea** | `gitea.yml` | 3002, 2222 | No | Git repository hosting (includes PostgreSQL) |
| **Samba** | `samba.yml` | 139, 445 | No | Network file sharing |
| **Open WebUI** | `open-webui.yml` | 8081 | No | AI chat interface with Ollama integration |
| **Core API** | `core-api.yml` | 8083 | No | Infrastructure management and AI orchestration |
| **Qdrant** | `qdrant.yml` | 6333, 6334 | No | Vector database for embeddings |
| **Organizr** | `organizr.yml` | 8084 | No | Unified dashboard |

### Shared Infrastructure

| Stack | File | Ports | GPU | Description |
|-------|------|-------|-----|-------------|
| **PostgreSQL Shared** | `postgres-shared.yml` | 5432 | No | Shared database for Nextcloud |
| **Redis Shared** | `redis-shared.yml` | 6379 | No | Shared cache for Nextcloud |

## Port Allocation

### Infrastructure Services (8000-8099)
- 8000: Nginx Proxy Manager (unified web interface)
- 8080: Portainer
- 8081: Open WebUI
- 8082: Nextcloud
- 8083: Core API
- 8084: Organizr
- 8085: Headscale
- 8096: Jellyfin

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

### Monitoring Services (3000-3999, 19000-19999)
- 3001: Uptime Kuma
- 8200: Duplicati
- 8888: Heimdall
- 19999: Netdata

### ML/API Services (11000+)
- 11434: Ollama
- 6333: Qdrant HTTP
- 6334: Qdrant gRPC

### Database Services
- 5432: PostgreSQL (shared)
- 6379: Redis (shared)

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

See [Shared Infrastructure Architecture](../architecture/SHARED_INFRASTRUCTURE_ARCHITECTURE.md) for database and cache sharing details.

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

See [GPU Docker Configuration](../guides/gpu-docker-config.md) for setup details.

## Deployment Checklist

### 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** - Plan the deployment

### 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
6. **Add monitoring** - Configure Uptime Kuma checks

## 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

Stacks are version-controlled in the `/stacks/` directory. Backup container data separately using the backup procedures.

See [Backup Procedures](../guides/backup-procedures.md) for details.

### 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

## Automation

The project includes automation scripts for stack management:

- `update-stack.sh` - Pull and update specific stack
- See [Automation Reference](AUTOMATION.md) for Portainer REST API usage

## Related Documentation

- [Container Reference](CONTAINERS.md) - Complete container profiles
- [System Specifications](SYSTEM.md) - Hardware and software specs
- [Shared Infrastructure Architecture](../architecture/SHARED_INFRASTRUCTURE_ARCHITECTURE.md) - Database/cache sharing
- [Maintenance Scripts](scripts.md) - Automated maintenance tasks