---
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 downgrading runc to 1.1.14.
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**: Required for unprivileged LXC configuration

## 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) - 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`:

```bash
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:
```bash
pct stop <CT_ID>
pct start <CT_ID>
```

### Step 4: Install Docker (Latest 28.x)

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

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

```bash
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

```bash
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:

```bash
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:
```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.