---
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.