Initial commit: Docker install skill for Ubuntu LXC containers

- Install Docker 28.0.4 (LXC-compatible) - Auto-configure Proxmox host permissions - Support Ubuntu 20.04/22.04/24.04 - Include troubleshooting guide
2026-03-26 13:44:59 +08:00
commit 88bcebe65b
2 changed files with 211 additions and 0 deletions
--- a/plugins/docker-install/skills/SKILL.md
+++ b/plugins/docker-install/skills/SKILL.md
@@ -0,0 +1,181 @@
+---
+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.
+tools: 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:
+
+```bash
+# 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:
+
+```bash
+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`:
+
+```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
+```
+
+Then restart the container:
+```bash
+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).
+
+```bash
+# 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:
+```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
+```
+
+### Step 5: Verify Installation
+
+```bash
+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:
+
+```bash
+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:
+```bash
+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.