Initial commit

2025-11-30 08:47:38 +08:00
commit 18faa0569e
47 changed files with 7969 additions and 0 deletions
--- a/skills/docker/references/proxmox/hosting.md
+++ b/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
+```
--- a/skills/docker/references/proxmox/lxc-vs-docker.md
+++ b/skills/docker/references/proxmox/lxc-vs-docker.md
@@ -0,0 +1,140 @@
+# LXC vs Docker Containers
+
+Understanding when to use Proxmox LXC containers vs Docker containers.
+
+## Fundamental Differences
+
+| Aspect | LXC (Proxmox) | Docker |
+|--------|---------------|--------|
+| Abstraction | System container (full OS) | Application container |
+| Init system | systemd, runit, etc. | Single process (PID 1) |
+| Management | Proxmox (pct) | Docker daemon |
+| Persistence | Stateful by default | Ephemeral by default |
+| Updates | apt/yum inside container | Replace container |
+| Networking | Proxmox managed | Docker managed |
+
+## When to Use LXC
+
+- **Long-running services** with traditional management (systemd, cron)
+- **Multi-process applications** that expect init system
+- **Legacy apps** not designed for containers
+- **Dev/test environments** mimicking full VMs
+- **Resource efficiency** when full VM isolation not needed
+- **Direct Proxmox management** (backup, snapshots, migration)
+
+```bash
+# Create LXC
+pct create 200 local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst \
+  --hostname mycontainer \
+  --storage local-lvm \
+  --rootfs local-lvm:8 \
+  --cores 2 \
+  --memory 2048 \
+  --net0 name=eth0,bridge=vmbr0,ip=dhcp
+```
+
+## When to Use Docker
+
+- **Microservices** with single responsibility
+- **CI/CD pipelines** with reproducible builds
+- **Rapid deployment** and scaling
+- **Application isolation** within a host
+- **Compose stacks** with multi-container apps
+- **Ecosystem tooling** (registries, orchestration)
+
+```yaml
+# docker-compose.yaml
+services:
+  app:
+    image: myapp:1.0
+    restart: unless-stopped
+```
+
+## Decision Matrix
+
+| Scenario | Recommendation | Rationale |
+|----------|---------------|-----------|
+| Pi-hole | Docker on VM | Easy updates, compose ecosystem |
+| Database server | LXC or VM | Stateful, traditional management |
+| Web app microservice | Docker | Ephemeral, scalable |
+| Development environment | LXC | Full OS, multiple services |
+| CI runner | Docker on VM | Isolation, reproducibility |
+| Network appliance | LXC | Direct network access, systemd |
+| Home automation | Docker on VM | Compose stacks, easy backup |
+
+## Hybrid Approach
+
+Common pattern: **VM runs Docker**, managed by Proxmox.
+
+```
+Proxmox Node
+├── VM: docker-host-1 (template 102)
+│   ├── Container: nginx
+│   ├── Container: app
+│   └── Container: redis
+├── VM: docker-host-2 (template 102)
+│   ├── Container: postgres
+│   └── Container: backup
+└── LXC: pihole (direct network)
+```
+
+Benefits:
+- Proxmox handles VM-level backup/migration
+- Docker handles application deployment
+- Clear separation of concerns
+
+## Docker in LXC (Not Recommended)
+
+Running Docker inside LXC is possible but adds complexity:
+
+### Requirements
+
+1. Privileged container OR nested containers enabled
+2. AppArmor profile modifications
+3. Keyctl feature enabled
+
+```bash
+# LXC config (Proxmox)
+lxc.apparmor.profile: unconfined
+lxc.cgroup.devices.allow: a
+lxc.cap.drop:
+features: keyctl=1,nesting=1
+```
+
+### Issues
+
+- Security: Reduced isolation
+- Compatibility: Some Docker features broken
+- Debugging: Two container layers
+- Backup: More complex
+
+**Recommendation:** Use VM with Docker instead.
+
+## Resource Comparison
+
+For equivalent workload:
+
+| Resource | VM + Docker | LXC | Docker in LXC |
+|----------|-------------|-----|---------------|
+| RAM overhead | ~500 MB | ~50 MB | ~100 MB |
+| Disk overhead | ~5 GB | ~500 MB | ~1 GB |
+| Boot time | 30-60s | 2-5s | 5-10s |
+| Isolation | Full | Shared kernel | Shared kernel |
+| Complexity | Low | Low | High |
+
+## Migration Paths
+
+### LXC to Docker
+
+1. Export application config from LXC
+2. Create Dockerfile/compose
+3. Build image
+4. Deploy to Docker host
+5. Migrate data volumes
+
+### Docker to LXC
+
+1. Install service directly in LXC (apt/yum)
+2. Configure with systemd
+3. Migrate data
+4. Update Proxmox firewall rules