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
This commit is contained in:
30
PLUGIN.md
Normal file
30
PLUGIN.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
name: docker-install
|
||||
description: Install Docker and docker-compose on Ubuntu LXC containers (Proxmox VE)
|
||||
version: 1.0.0
|
||||
author: Your Name
|
||||
---
|
||||
|
||||
# Docker Install Plugin
|
||||
|
||||
Quickly install Docker and docker-compose on empty Ubuntu LXC containers with automatic LXC compatibility handling.
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`bash
|
||||
claude plugin install https://github.com/YOUR_USERNAME/docker-install-plugin
|
||||
\`\`\`
|
||||
|
||||
## Usage
|
||||
|
||||
Invoke the skill:
|
||||
- `/docker-install` - Full guided installation
|
||||
- Or describe: "Install Docker on this CT"
|
||||
|
||||
## What It Does
|
||||
|
||||
- Detects LXC container type (privileged/unprivileged)
|
||||
- Configures Proxmox host device permissions
|
||||
- Installs Docker 28.0.4 (LXC-compatible, avoids runc 1.3.4 issues)
|
||||
- Verifies installation with hello-world test
|
||||
- Optionally locks versions to prevent upgrades
|
||||
181
plugins/docker-install/skills/SKILL.md
Normal file
181
plugins/docker-install/skills/SKILL.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user