docker-install-plugin/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 downgrading runc to 1.1.14.	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: Required for unprivileged LXC configuration

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

For basic Docker functionality, no special Proxmox host configuration is required when using runc 1.1.14 (see Step 5).

If you encounter device access issues, add to /etc/pve/lxc/<CT_ID>.conf:

lxc.cgroup2.devices.allow: c 226:* 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 (Latest 28.x)

# 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

# Update package list
apt-get update

# Install latest Docker 28.x (check available with: apt-cache madison docker-ce)
DOCKER_VERSION=$(apt-cache madison docker-ce | grep -E "28\." | head -1 | cut -d"|" -f2 | tr -d " ")
apt-get install -y docker-ce=${DOCKER_VERSION} docker-ce-cli=${DOCKER_VERSION} containerd.io docker-buildx-plugin docker-compose-plugin

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

Step 5: Downgrade runc to 1.1.14

CRITICAL: Docker 28.x+ uses runc 1.2+ which has compatibility issues with unprivileged LXC containers. Must downgrade to runc 1.1.14.

ssh root@<CT_IP> bash -c '
# Download and install runc 1.1.14
cd /tmp
wget https://github.com/opencontainers/runc/releases/download/v1.1.14/runc.amd64
install -m 755 runc.amd64 /usr/bin/runc

# Restart Docker
systemctl restart docker

# Verify runc version
runc -version

# Clean up
rm -f /tmp/runc.amd64
'

Step 6: Verify Installation

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

Expected output:

Docker version 28.x.x, build xxxx
Docker Compose version vx.x.x
runc version 1.1.14
Hello from Docker!
...

Step 7: Lock Versions (Recommended)

Prevent automatic upgrades:

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

Troubleshooting

Error: ip_unprivileged_port_start permission denied

Cause: runc 1.2+ in unprivileged LXC Solution: Downgrade runc to 1.1.14 (see Step 5)

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.x (latest available)
containerd	2.x
runc	1.1.14
Docker Compose	v5.x

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.