From 94f5467a37a455525ad48a7b395555ba65989757 Mon Sep 17 00:00:00 2001 From: Timmy Date: Thu, 26 Mar 2026 15:08:36 +0800 Subject: [PATCH] Update docker-install skill: add runc 1.1.14 downgrade for LXC compatibility --- plugins/docker-install/skills/SKILL.md | 83 ++++++++++++++------------ 1 file changed, 44 insertions(+), 39 deletions(-) diff --git a/plugins/docker-install/skills/SKILL.md b/plugins/docker-install/skills/SKILL.md index 7fdd394..5e8667b 100644 --- a/plugins/docker-install/skills/SKILL.md +++ b/plugins/docker-install/skills/SKILL.md @@ -1,6 +1,6 @@ --- name: docker-install -description: 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. +description: 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. tools: Read, Glob, Grep, Bash --- @@ -12,7 +12,7 @@ Install Docker and docker-compose on an empty Ubuntu LXC container (Proxmox VE). - **Target**: Empty Ubuntu LXC container (CT) - **Access**: SSH access to the CT as root -- **Proxmox Host**: May need access to configure LXC device permissions +- **Proxmox Host**: Required for unprivileged LXC configuration ## Workflow @@ -38,14 +38,14 @@ ssh root@ "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) +### Step 3: Configure Proxmox Host (for Unprivileged LXC) - Optional -SSH to Proxmox host and add device permissions to `/etc/pve/lxc/.conf`: +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/.conf`: ```bash -# 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 ``` @@ -56,9 +56,7 @@ pct stop pct start ``` -### 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). +### Step 4: Install Docker (Latest 28.x) ```bash # On the CT: @@ -78,69 +76,76 @@ echo \ $(. /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 +# Update package list +apt-get update -# 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 +# 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 - -# Clean up -rm -f /tmp/*.deb ' ``` -**For Ubuntu 22.04 (jammy)**, replace `noble` with `jammy` in URLs: +### 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. + ```bash -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 +ssh root@ 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 5: Verify Installation +### Step 6: Verify Installation ```bash ssh root@ " docker --version docker compose version +runc -version docker run --rm hello-world " ``` **Expected output**: ``` -Docker version 28.0.4, build b8034c0 -Docker Compose version v2.29.1 +Docker version 28.x.x, build xxxx +Docker Compose version vx.x.x +runc version 1.1.14 Hello from Docker! ... ``` -### Step 6: Lock Versions (Optional but Recommended) +### Step 7: Lock Versions (Recommended) -Prevent automatic upgrades to Docker 29.x: +Prevent automatic upgrades: ```bash -ssh root@ "apt-mark hold docker-ce docker-ce-cli containerd.io" +ssh root@ "apt-mark hold docker-ce docker-ce-cli containerd.io runc" ``` ## 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) +**Cause**: runc 1.2+ in unprivileged LXC +**Solution**: Downgrade runc to 1.1.14 (see Step 5) ### Error: `Cannot connect to Docker daemon` @@ -156,10 +161,10 @@ ssh root@ "apt-mark hold docker-ce docker-ce-cli containerd.io" | Component | Version | |-----------|---------| -| Docker | 28.0.4 | -| containerd | 1.7.22 | +| Docker | 28.x (latest available) | +| containerd | 2.x | | runc | 1.1.14 | -| Docker Compose | v2.29.1 | +| Docker Compose | v5.x | ## Alternative: Privileged LXC Container