docker-install-plugin/plugins/docker-install/skills/SKILL.md

name, description, tools

name	description	tools
docker-install	Install Docker and docker-compose on Ubuntu LXC container (Proxmox). Use when user wants to install Docker on an empty Ubuntu CT, or asks to set up Docker/docker-compose on a fresh container. Automatically handles LXC compatibility by using Docker 28.0.4 instead of 29.x.	Read, Glob, Grep, Bash

Docker Install for Ubuntu LXC Container

Install Docker and docker-compose on an empty Ubuntu LXC container (Proxmox VE).

Prerequisites

• Target: Empty Ubuntu LXC container (CT)
• Access: SSH access to the CT as root
• Proxmox Host: May need access to configure LXC device permissions

Workflow

Step 1: Identify Target

Ask user for the CT IP address:

# Example: CT at 192.168.42.123
ssh root@192.168.42.123 "cat /etc/os-release"

Verify: OS is Ubuntu 20.04/22.04/24.04

Step 2: Check LXC Configuration

Check if container is unprivileged LXC:

ssh root@<CT_IP> "cat /proc/self/uid_map"

If shows 0 100000 65536 → Unprivileged LXC (needs special config) If shows 0 0 4294967295 → Privileged LXC (standard install OK)

Step 3: Configure Proxmox Host (for Unprivileged LXC)

SSH to Proxmox host and add device permissions to /etc/pve/lxc/<CT_ID>.conf:

# Add to container config:
lxc.cgroup2.devices.allow: c 226:* rwm
lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file
lxc.prlimit.nofile: 65535:65535

Then restart the container:

pct stop <CT_ID>
pct start <CT_ID>

Step 4: Install Docker 28.0.4

IMPORTANT: Use Docker 28.0.4, NOT 29.x. Docker 29.x uses runc 1.3.4 which has compatibility issues with unprivileged LXC containers (ip_unprivileged_port_start permission error).

# On the CT:
ssh root@<CT_IP> bash -c '
# Update and install prerequisites
apt-get update
apt-get install -y ca-certificates curl gnupg

# Add Docker GPG key
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  tee /etc/apt/sources.list.d/docker.list > /dev/null

# Download Docker 28.0.4 packages (workaround for LXC compatibility)
cd /tmp
wget https://download.docker.com/linux/ubuntu/pool/stable/d/docker-ce-cli/docker-ce-cli_5%3A28.0.4-1~ubuntu.24.04~noble_amd64.deb
wget https://download.docker.com/linux/ubuntu/pool/stable/d/containerd.io/containerd.io_1.7.22-1_amd64.deb
wget https://download.docker.com/linux/ubuntu/pool/stable/d/docker-ce/docker-ce_5%3A28.0.4-1~ubuntu.24.04~noble_amd64.deb
wget https://download.docker.com/linux/ubuntu/pool/stable/d/docker-buildx-plugin/docker-buildx-plugin_0.17.1-1~ubuntu.24.04~noble_amd64.deb
wget https://download.docker.com/linux/ubuntu/pool/stable/d/docker-compose-plugin/docker-compose-plugin_2.29.1-1~ubuntu.24.04~noble_amd64.deb

# Install packages
dpkg -i containerd.io_1.7.22-1_amd64.deb
dpkg -i docker-ce-cli_5%3A28.0.4-1~ubuntu.24.04~noble_amd64.deb
dpkg -i docker-ce_5%3A28.0.4-1~ubuntu.24.04~noble_amd64.deb
dpkg -i docker-buildx-plugin_0.17.1-1~ubuntu.24.04~noble_amd64.deb
dpkg -i docker-compose-plugin_2.29.1-1~ubuntu.24.04~noble_amd64.deb

# Start and enable Docker
systemctl daemon-reload
systemctl start docker
systemctl enable docker

# Clean up
rm -f /tmp/*.deb
'

For Ubuntu 22.04 (jammy), replace noble with jammy in URLs:

wget https://download.docker.com/linux/ubuntu/pool/stable/d/docker-ce/docker-ce_5%3A28.0.4-1~ubuntu.22.04~jammy_amd64.deb
# ... etc

Step 5: Verify Installation

ssh root@<CT_IP> "
docker --version
docker compose version
docker run --rm hello-world
"

Expected output:

Docker version 28.0.4, build b8034c0
Docker Compose version v2.29.1
Hello from Docker!
...

Step 6: Lock Versions (Optional but Recommended)

Prevent automatic upgrades to Docker 29.x:

ssh root@<CT_IP> "apt-mark hold docker-ce docker-ce-cli containerd.io"

Troubleshooting

Error: ip_unprivileged_port_start permission denied

Cause: Docker 29.x with runc 1.3.4 in unprivileged LXC Solution: Downgrade to Docker 28.0.4 (see Step 4)

Error: Cannot connect to Docker daemon

Cause: Docker not running Solution: systemctl start docker

Error: Permission denied during SSH

Cause: SSH keys not set up Solution: Use ssh-copy-id root@<CT_IP> from local machine

Quick Reference

Component	Version
Docker	28.0.4
containerd	1.7.22
runc	1.1.14
Docker Compose	v2.29.1

Alternative: Privileged LXC Container

If Proxmox host access is not available, convert container to privileged mode:

Proxmox Web UI:

1. Select CT → Options → Edit Privileged
2. Check Privileged
3. Restart CT

Or via CLI on Proxmox host:

vi /etc/pve/lxc/<CT_ID>.conf
# Add: unprivileged: 0
pct stop <CT_ID>
pct start <CT_ID>

Warning: Privileged containers have security implications. Only use in trusted environments.