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:

{"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:

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

# 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.):

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

3.6 KiB Raw Blame History