How to Install Docker on Debian 12 Step by Step

This guide covers installing Docker Engine on Debian 12 (Bookworm) from Docker’s official repository — the recommended method to get the latest version and continuous security support. Includes installation verification, docker group configuration for sudo-less use, and troubleshooting of the most common issues.

Why From the Official Repository

Debian includes docker.io in its official repos, but there are reasons to prefer Docker’s repo:

Latest version. Debian’s repo lags; Docker’s has the latest stable.
Fast security updates. Docker patches reach the official repo before Debian’s.
Components updated together. Engine, CLI, containerd, and BuildKit aligned.
Compatibility with the docker-compose v2 plugin, which is the current version.

The Debian package works but ages faster. For serious production, official repository.

Step 1: Clean Previous Installations

If you have old Docker or docker.io installed:

sudo apt-get remove docker docker-engine docker.io containerd runc

This removes packages but doesn’t delete images or data from /var/lib/docker. To start from scratch, also:

sudo rm -rf /var/lib/docker
sudo rm -rf /var/lib/containerd

Step 2: Prepare the System

Update indexes and install dependencies to add the repo:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

Step 3: Add Docker’s Official GPG Key

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

This places the GPG key in /etc/apt/keyrings/, the modern location recommended by Debian/Ubuntu (instead of deprecated apt-key add).

Step 4: Add the Repository

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

This automatically detects architecture (amd64 or arm64) and release name (bookworm for Debian 12).

Step 5: Install Docker

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Five packages:

docker-ce: the daemon (Docker Community Edition).
docker-ce-cli: the docker command.
containerd.io: the low-level runtime.
docker-buildx-plugin: advanced build (multi-arch).
docker-compose-plugin: the v2 docker compose (with space).

After installation, the service starts automatically.

Step 6: Verify It Works

sudo docker --version
sudo docker compose version
sudo docker run hello-world

hello-world downloads a minimal image, runs it, and prints a message confirming the install is functional.

Step 7: Allow Use Without sudo

For security, Docker requires sudo by default. To use docker as a normal user:

sudo usermod -aG docker $USER
newgrp docker

newgrp updates the current session. For new sessions, just close and reopen terminal or SSH session.

⚠ Security implication: adding a user to the docker group is practically equivalent to giving them root. Whoever can run docker run can mount / and modify whatever they want. On shared servers or serious production, consider rootless Docker instead.

Step 8: Enable Auto-start at Boot

If it wasn’t already:

sudo systemctl enable docker.service
sudo systemctl enable containerd.service

Now Docker starts when the machine boots.

Recommended Configuration (Optional)

Edit /etc/docker/daemon.json (create it if it doesn’t exist) to configure log rotation and other good practices:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "live-restore": true
}

log-driver and log-opts: limit log size (without this, a chatty container can fill the disk).
live-restore: containers keep running if you restart dockerd (useful for upgrades).

Apply with:

sudo systemctl reload docker

Common Problems

`permission denied` when running `docker`

Means the docker group wasn’t applied to your session. Run newgrp docker or close and reopen session.

`Cannot connect to the Docker daemon`

Verify the service is running:

sudo systemctl status docker

If it fails to start, check logs:

sudo journalctl -u docker -n 100 --no-pager

Slow Pull or DNS Errors

Configure a local Docker Hub mirror or use a registry cache if your Internet connection is limited. registry-mirrors variable in daemon.json.

Lack of Space

Docker accumulates images and layers. Clean periodically:

docker system prune -a --volumes

(Careful: this deletes everything unused, including anonymous volumes.)

Next Steps

With Docker installed you can:

Try Docker Compose to define multi-service stacks.
Consider Docker Swarm if you need lightweight orchestration.
Configure logs and metrics to Prometheus/Loki.
Use Watchtower for container auto-update in monitor mode.

Conclusion

Installing Docker on Debian 12 from the official repo is a predictable, well-documented process. Essential steps are: clean previous installs, add GPG key and official repo, install packages, configure docker group, verify operation. With log-rotation and live-restore details applied from the start, you have a solid base for light production or development.