Initial commit

skills/docker/references/proxmox/hosting.md

@@ -0,0 +1,227 @@
+# Docker on Proxmox VMs
+
+Best practices for running Docker workloads on Proxmox VE.
+
+## Template Selection
+
+Use Docker-ready templates (102+) which have Docker pre-installed:
+
+| Template ID | Name | Docker? |
+|-------------|------|---------|
+| 100 | tmpl-ubuntu-2404-base | No |
+| 101 | tmpl-ubuntu-2404-standard | No |
+| 102 | tmpl-ubuntu-2404-docker | Yes |
+| 103 | tmpl-ubuntu-2404-github-runner | Yes |
+| 104 | tmpl-ubuntu-2404-pihole | Yes |
+
+**DO NOT** install Docker via cloud-init on templates 102+.
+
+## VM vs LXC for Docker
+
+| Factor | VM (QEMU) | LXC Unprivileged | LXC Privileged |
+|--------|-----------|------------------|----------------|
+| Docker support | Full | Limited | Works but risky |
+| Isolation | Complete | Shared kernel | Shared kernel |
+| Overhead | Higher | Lower | Lower |
+| Nested containers | Works | Requires config | Works |
+| GPU passthrough | Yes | Limited | Limited |
+| Security | Best | Good | Avoid |
+
+**Recommendation:** Use VMs for Docker workloads. LXC adds complexity for marginal resource savings.
+
+## VM Sizing for Docker
+
+### Minimum for Docker host
+
+```
+CPU: 2 cores
+RAM: 4 GB (2 GB for OS, 2 GB for containers)
+Disk: 50 GB (20 GB OS, 30 GB images/volumes)
+```
+
+### Per-container overhead
+
+```
+Base: ~10 MB RAM per container
+Image layers: Shared between containers
+Volumes: Depends on data
+```
+
+### Sizing formula
+
+```
+Total RAM = 2 GB (OS) + sum(container memory limits) + 20% buffer
+Total Disk = 20 GB (OS) + images + volumes + 20% buffer
+```
+
+## Storage Backend Selection
+
+| Proxmox Storage | Docker Use Case | Performance |
+|-----------------|-----------------|-------------|
+| local-lvm | General workloads | Good |
+| ZFS | Database containers | Better (snapshots) |
+| Ceph | HA workloads | Good (distributed) |
+| NFS | Shared config/data | Moderate |
+
+### Volume mapping to Proxmox storage
+
+```yaml
+# docker-compose.yaml
+volumes:
+  db_data:
+    driver: local
+    driver_opts:
+      type: none
+      device: /mnt/storage/mysql  # Map to Proxmox storage mount
+      o: bind
+```
+
+## Network Considerations
+
+### Bridge mode (default)
+
+Container gets private IP, NAT to VM IP. Good for most workloads.
+
+```yaml
+services:
+  web:
+    ports:
+      - "80:80"  # VM_IP:80 -> container:80
+```
+
+### Host mode
+
+Container shares VM network stack. Use for network tools or performance.
+
+```yaml
+services:
+  pihole:
+    network_mode: host  # Container uses VM's IPs directly
+```
+
+### Macvlan (direct LAN access)
+
+Container gets own IP on Proxmox bridge.
+
+```bash
+# On Docker host (VM)
+docker network create -d macvlan \
+  --subnet=192.168.1.0/24 \
+  --gateway=192.168.1.1 \
+  -o parent=eth0 \
+  lan
+```
+
+```yaml
+services:
+  app:
+    networks:
+      lan:
+        ipv4_address: 192.168.1.50
+
+networks:
+  lan:
+    external: true
+```
+
+**Note:** Requires Proxmox bridge without VLAN tagging on that interface, or pass-through the VLAN-tagged interface to VM.
+
+## Resource Limits
+
+Always set limits to prevent container runaway affecting VM:
+
+```yaml
+services:
+  app:
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 2G
+        reservations:
+          cpus: '0.5'
+          memory: 512M
+```
+
+## GPU Passthrough
+
+For containers needing GPU (AI/ML, transcoding):
+
+1. **Proxmox:** Pass GPU to VM
+   ```
+   hostpci0: 0000:01:00.0,pcie=1
+   ```
+
+2. **VM:** Install NVIDIA drivers + nvidia-container-toolkit
+
+3. **Compose:**
+   ```yaml
+   services:
+     plex:
+       deploy:
+         resources:
+           reservations:
+             devices:
+               - driver: nvidia
+                 count: 1
+                 capabilities: [gpu]
+   ```
+
+## Backup Considerations
+
+### What to backup
+
+| Data | Method | Location |
+|------|--------|----------|
+| VM disk | Proxmox vzdump | Includes everything |
+| Docker volumes | docker run --volumes-from | Application-level |
+| Compose files | Git | Version control |
+
+### Proxmox backup includes Docker
+
+When backing up the VM with vzdump, all Docker data (images, volumes, containers) is included.
+
+```bash
+vzdump <vmid> --mode snapshot --storage backup
+```
+
+### Application-consistent backups
+
+For databases, use pre/post scripts:
+
+```bash
+# Pre-backup: flush and lock
+docker exec mysql mysql -e "FLUSH TABLES WITH READ LOCK;"
+
+# vzdump runs...
+
+# Post-backup: unlock
+docker exec mysql mysql -e "UNLOCK TABLES;"
+```
+
+## Troubleshooting
+
+### Container can't reach internet
+
+1. Check VM can reach internet: `ping 8.8.8.8`
+2. Check Docker DNS: `docker run --rm alpine nslookup google.com`
+3. Check iptables forwarding: `sysctl net.ipv4.ip_forward`
+
+### Port not accessible from LAN
+
+1. Check Proxmox firewall allows port
+2. Check VM firewall (ufw/iptables)
+3. Check container is bound to 0.0.0.0 not 127.0.0.1
+
+### Disk space issues
+
+```bash
+# Check Docker disk usage
+docker system df
+
+# Clean up
+docker system prune -a --volumes  # WARNING: removes all unused data
+
+# Check VM disk
+df -h
+```