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:

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

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

# 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

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

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

# 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

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

# 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

# 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

# Check your group memberships
groups

# Should show 'docker' in the list

Step 5.3: Test Without sudo

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

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)

# 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

# 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

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

# 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

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

cat /etc/os-release

Verify repository file:

cat /etc/apt/sources.list.d/docker.sources

Re-add repository if needed:

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:

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

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

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

#!/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/