# Docker Inside Proxmox LXC: Systematic Failure

## TL;DR

**Never install Docker inside a Proxmox LXC container.** Use a QEMU VM (`qm create`) instead. Docker requires kernel capabilities (module loading, bridge networking, iptables NAT chains, full cgroup hierarchy) that LXC does not provide.

## Test Environment

- CT 120 on n5pro (10.0.20.91), Debian 12 Bookworm
- Attempted: `apt-get install docker-ce docker-ce-cli containerd.io`
- Goal: Run Frigate 0.17.2 Docker image (`stable-rocm`) inside the existing LXC

## Failure Cascade

### 1. docker.socket: Group Not Found

```
docker.socket: Failed to resolve group docker: No such process
docker.socket: Control process exited, code=exited, status=216/GROUP
```

**Cause:** Docker install didn't create the `docker` group (interrupted apt-get).
**Fix attempted:** `groupadd docker` — socket starts, but daemon still fails.

### 2. dockerd: iptables not found

```
failed to start daemon: Error initializing network controller:
error obtaining controller instance:
failed to register "bridge" driver:
failed to create NAT chain DOCKER: iptables not found
```

**Cause:** `iptables` binary existed as `iptables-nft` but the `iptables` symlink was missing.
**Fix attempted:** `ln -sf /sbin/iptables-nft /sbin/iptables` — iptables works, but daemon still fails.

### 3. dockerd: ip6tables not found

```
unable to find ip6tables: executable file not found in $PATH
```

**Fix attempted:** Created ip6tables symlinks. Daemon progresses further but still fails.

### 4. modprobe overlay fails (ExecStartPre)

```
containerd.service: Process: 2182 ExecStartPre=/sbin/modprobe overlay (code=exited, status=1/FAILURE)
```

**Cause:** LXC containers cannot load kernel modules. The `overlay` filesystem IS available (visible in `/proc/filesystems`) but `modprobe` itself fails because it can't access `/lib/modules/$(uname -r)`.

### 5. Bridge driver fails even with iptables=false

Attempted `daemon.json`:
```json
{"iptables": false, "bridge": "none", "ip6tables": false}
```

Still fails because containerd has its own overlayfs and cgroup requirements that LXC doesn't satisfy.

### 6. dpkg Database Corruption

Interrupted apt-get (due to timeouts on slow package downloads) left dpkg in a broken state:

```
dpkg: unrecoverable fatal error, aborting:
 unable to install updated status of 'apparmor': No such file or directory
E: dpkg was interrupted, you must manually run 'dpkg --configure -a' to correct the problem.
```

**Recovery:**
```bash
# Inside the CT
rm -f /var/lib/dpkg/updates/*
dpkg --configure -a --force-all
# May need to run multiple times
```

## Recovery Steps (After Failed Docker Install)

```bash
# 1. Stop Docker services
systemctl stop docker docker.socket containerd 2>/dev/null
systemctl disable docker docker.socket containerd 2>/dev/null

# 2. Fix dpkg
rm -f /var/lib/dpkg/updates/*
dpkg --configure -a --force-all

# 3. Purge Docker
apt-get purge -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
apt-get autoremove -y

# 4. Clean up
rm -rf /var/lib/docker /var/lib/containerd /etc/docker

# 5. Verify original service still works
systemctl restart frigate.service  # or whatever was running before
```

## Correct Approach: QEMU VM

For any workload requiring Docker (Frigate, Portainer, etc.):

```bash
# Create VM on the Proxmox node
qm create <VMID> --name <name> --memory 8192 --cores 4 \
  --net0 virtio,bridge=vmbr0 --ostype l26
# Add disk, install Debian, then install Docker normally
```

GPU passthrough for QEMU VMs uses `hostpci` in the VM config:
```
hostpci0: 0000:xx:yy.z,pcie=1
```

This gives full kernel access, proper cgroup support, and Docker works natively.