kdb/docker-debian-install-report-2026-05-14.md

# Docker Installation on Debian - Official Documentation Report

**Date:** 2026-05-14  
**Source:** https://docs.docker.com/engine/install/debian/

---

## 1. Prerequisites

### Supported Debian Versions
- **Debian Trixie 13** (stable)
- **Debian Bookworm 12** (oldstable)
- **Debian Bullseye 11** (oldoldstable)

### Supported Architectures
- x86_64 (amd64)
- armhf (arm/v7)
- arm64
- ppc64le (ppc64el)

### Firewall Considerations
- Docker is only compatible with `iptables-nft` and `iptables-legacy`
- Firewall rules created with `nft` are **not supported** with Docker
- Use `iptables` or `ip6tables` for firewall rules
- Add rules to the `DOCKER-USER` chain

---

## 2. Remove Old/Conflicting Versions

Before installing Docker Engine, remove any conflicting packages:

```bash
# Remove old Docker packages that may conflict
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-doc podman-docker containerd runc | cut -f1)
```

**Packages removed:**
- `docker.io` - Debian distribution's Docker package (NOT the official Docker version)
- `docker-compose` - Standalone compose tool
- `docker-doc` - Documentation packages
- `podman-docker` - Podman Docker compatibility layer
- `containerd` - Container runtime (if installed separately)
- `runc` - Container runtime (if installed separately)

**Note:** This command may report "none of these packages are installed" on fresh systems - that's normal.

**Important:** Containers, images, volumes, and networks in `/var/lib/docker/` are NOT automatically removed. To start completely clean:
```bash
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd
```

---

## 3. Installation Methods Overview

| Method | Use Case | Recommendation |
|--------|----------|----------------|
| **Docker Desktop for Linux** | Easiest setup, includes GUI | Recommended for developers |
| **apt repository** | Production, automated updates | **Recommended for most users** |
| **Manual .deb installation** | Air-gapped systems | For offline installations |
| **Convenience script** | Testing/development only | NOT recommended for production |

---

## 4. RECOMMENDED: Install from Docker's apt Repository

### Step 4.1: Set Up Docker's apt Repository

```bash
# Update package index
sudo apt update

# Install prerequisites (ca-certificates enables HTTPS, curl downloads files)
sudo apt install ca-certificates curl

# Create keyrings directory with proper permissions
sudo install -m 0755 -d /etc/apt/keyrings

# Download Docker's official GPG key
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc

# Set readable permissions on the key file
sudo chmod a+r /etc/apt/keyrings/docker.asc
```

**What each command does:**
- `ca-certificates` - Required for HTTPS connections to repository
- `curl` - Downloads files over HTTP/HTTPS
- `-m 0755` - Sets directory permissions (rwxr-xr-x)
- `-fsSL` on curl: follow redirects, silent mode, fail on errors, use SSL

### Step 4.2: Add Docker Repository to APT Sources

```bash
# Add Docker repository (NEW FORMAT for Debian)
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

# Update package index to include new repository
sudo apt update
```

**What this does:**
- Creates a new `.sources` file (Debian 12+ format)
- Automatically detects your Debian version (bookworm, bullseye, trixie)
- Automatically detects your system architecture
- Points to Docker's official repository

**Alternative format** (older systems still work):
```bash
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
```

### Step 4.3: Install Docker Engine

```bash
# Install Docker Engine, CLI, containerd, and plugins
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

**Packages installed:**
| Package | Description |
|---------|-------------|
| `docker-ce` | Docker Community Edition - the main engine |
| `docker-ce-cli` | Docker CLI (command-line interface) |
| `containerd.io` | Container runtime (dependency) |
| `docker-buildx-plugin` | Buildx for multi-platform builds |
| `docker-compose-plugin` | Docker Compose as `docker compose` command |

### Step 4.4: Verify Installation

```bash
# Run the hello-world container to verify installation
sudo docker run hello-world
```

**Expected output:**
```
Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image...
```

### Step 4.5: Install Specific Version (Optional)

```bash
# List all available versions
apt list --all-versions docker-ce

# Install specific version (example)
VERSION_STRING=5:29.4.3-1~debian.12~bookworm
sudo apt install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin
```

---

## 5. Post-Installation: Run Docker Without sudo

### Step 5.1: Add User to docker Group

```bash
# Add current user to docker group
sudo usermod -aG docker $USER

# Apply group change without logging out
newgrp docker
```

**What this does:**
- `usermod -aG` - Appends user to supplementary group (doesn't remove from other groups)
- `$USER` - Environment variable for current username
- `newgrp docker` - Starts new shell with updated group membership

**Alternative:** Log out and log back in completely for group change to take effect.

### Step 5.2: Verify Group Membership

```bash
# Check your group memberships
groups

# Should show 'docker' in the list
```

### Step 5.3: Test Without sudo

```bash
# Now you can run Docker commands without sudo
docker run hello-world
docker ps
```

---

## 6. Alternative: Install Docker Desktop for Linux

Docker Desktop for Linux includes Docker Engine plus additional features:
- GUI desktop application
- Kubernetes support
- Image building and management
- Extension marketplace

**Installation:**
1. Download `.deb` package from: https://www.docker.com/products/docker-desktop/
2. Install with:
```bash
sudo dpkg -i docker-desktop-*.deb
sudo apt-get install -f  # Fix any dependencies
```

**Note:** Docker Desktop for Linux requires a subscription for commercial use in larger enterprises (>250 employees OR >$10M annual revenue).

---

## 7. Alternative: Convenience Script (Development Only)

```bash
# Download and run the script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```

**WARNING:** Only use for testing/development. The script:
- Requires root/sudo privileges
- Auto-detects distribution (may be incorrect)
- Installs latest version without confirmation
- Doesn't allow customization
- Not designed for production upgrades

---

## 8. Upgrade Docker Engine

```bash
# Simply upgrade using apt
sudo apt update
sudo apt upgrade docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

---

## 9. Uninstall Docker Engine

```bash
# Remove Docker packages
sudo apt purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Remove Docker data (optional - images, containers, volumes)
sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd

# Remove repository configuration
sudo rm /etc/apt/sources.list.d/docker.sources
sudo rm /etc/apt/keyrings/docker.asc
```

---

## 10. Troubleshooting Common Issues

### Issue: "Permission denied while trying to connect to Docker daemon socket"

**Error:**
```
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
```

**Solution:**
```bash
# Add user to docker group
sudo usermod -aG docker $USER

# Activate the group immediately (or log out/in)
newgrp docker

# Verify
groups
docker run hello-world
```

### Issue: Docker service not running

```bash
# Check service status
sudo systemctl status docker

# Start Docker service
sudo systemctl start docker

# Enable Docker to start on boot
sudo systemctl enable docker
```

### Issue: Repository not found / No matching packages

**Check your Debian version:**
```bash
cat /etc/os-release
```

**Verify repository file:**
```bash
cat /etc/apt/sources.list.d/docker.sources
```

**Re-add repository if needed:**
```bash
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
```

### Issue: Firewall rules not working

Docker bypasses firewall rules when exposing container ports. Use the `DOCKER-USER` chain:
```bash
# Add rules to DOCKER-USER chain
sudo iptables -I DOCKER-USER 1 -i eth0 -j DROP
```

---

## 11. Security Considerations

### The docker Group = Root Access

**WARNING:** Adding a user to the `docker` group gives them effectively root access because:

```bash
# Mount host filesystem and gain root shell
docker run -v /:/host -it ubuntu chroot /host bash
```

**Recommendations:**
- Only add trusted administrators to the docker group
- On multi-user systems, consider **Rootless Docker** instead
- Use rootless Docker for development:
```bash
# Install rootless Docker
sudo apt install uidmap dbus-user-session
dockerd-rootless-setuptool.sh install
```

### Docker Desktop Licensing

Commercial use of Docker Desktop in enterprises (>250 employees OR >$10M revenue) requires a paid subscription. Docker Engine (CLI installation) remains under Apache 2.0 license.

---

## 12. Quick Copy-Paste Installation Script

For a complete fresh installation:

```bash
#!/bin/bash
# Complete Docker installation on Debian

# 1. Remove old versions
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-doc podman-docker containerd runc | cut -f1) 2>/dev/null

# 2. Install prerequisites
sudo apt update
sudo apt install -y ca-certificates curl

# 3. Set up Docker repository
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

# 4. Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 5. Add user to docker group
sudo usermod -aG docker $USER

# 6. Enable and start Docker
sudo systemctl enable docker
sudo systemctl start docker

echo "Docker installation complete. Run 'newgrp docker' or log out/in to use Docker without sudo."
```

---

## References

- **Official Documentation:** https://docs.docker.com/engine/install/debian/
- **Docker Download:** https://download.docker.com/linux/debian/
- **Docker Desktop:** https://www.docker.com/products/docker-desktop/
- **Convenience Script:** https://get.docker.com/