Updated: 2026-06-20

Installing Docker on Debian 12 looks like a mechanical errand — copy four commands and done — but hidden inside that process are decisions that shape the next twelve months of operation. Which repository to use, how to manage permissions, and what to put in daemon.json from the very first boot are questions with real consequences when the machine graduates from experiment to exposed service.

Key takeaways

  • Debian’s docker.io package trails several minors behind; the official Docker repository is the only reasonable choice for production.
  • The standard install requires five packages: docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, and docker-compose-plugin.
  • Membership in the docker group is practically equivalent to root on the machine; evaluate rootless Docker on shared servers.
  • Configure log rotation and live-restore in daemon.json from day one to avoid the most common problems.
  • The docker run hello-world that prints the green message is the beginning, not the end.

Why Not the Debian Package

Debian ships docker.io in its repositories, and for tinkering on a laptop that is fine. Once the machine does real work, the distribution package falls short:

  • The packaged version trails Docker’s stable branch by several minors.
  • Security patches take longer to land.
  • Components — engine, CLI, containerd, BuildKit — are not updated as a coordinated set.

Docker’s official repository solves all three: you get the current version, patches arrive the day they are released, and components move together. The docker compose v2 plugin also comes packaged alongside the engine, ending the historical dance between hyphenated docker-compose and space-separated docker compose.

Preparing the Ground

Before adding anything new, remove any previous install:

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

This cleans the binaries without touching images or volumes in /var/lib/docker and /var/lib/containerd. With the system clean, update APT and install the minimum dependencies for adding a signed repository:

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

GPG Key and Repository

Debian’s modern method for repository keys is to drop them into /etc/apt/keyrings/ as individual files. The old apt-key add has been deprecated for years because a globally installed key implicitly signs any repository, breaking APT’s isolation.

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

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

The signed-by= directive makes the key exclusive to that repository — APT will only accept Docker signatures for packages from download.docker.com.

Bash logo, the command interpreter used to run all Docker installation steps on Debian

Installing the Right Packages

Docker is not a single binary but a collection of pieces:

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

What each does:

  • docker-ce: the dockerd daemon listening on the Unix socket and orchestrating containers.
  • docker-ce-cli: the docker client that talks to the daemon.
  • containerd.io: the low-level runtime that launches containers.
  • docker-buildx-plugin: multi-platform builds with BuildKit.
  • docker-compose-plugin: declarative v2 orchestrator.

After the install, systemd starts the service and leaves it enabled.

Verification and the docker Group

Three commands confirm everything is in place:

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

If the last fails but the first two succeed, the problem is usually DNS or the registry, not the install.

Adding your user to the docker group looks cosmetic but carries serious security implications. Group membership is practically equivalent to root on that machine: anyone who can run docker run can mount the root filesystem inside a privileged container. On a shared server, evaluate rootless Docker. On a personal box, the group is acceptable if you understand the trade-off.

sudo usermod -aG docker $USER
newgrp docker

Configuration That Prevents Surprises

The file /etc/docker/daemon.json is empty by default. Leaving it that way is the first production mistake almost everyone makes. Two parameters that deserve to be set from day one:

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

Without log rotation, a chatty container fills the disk in days. With live-restore, containers survive a daemon restart — Docker upgrades stop taking services down. Apply changes with sudo systemctl reload docker.

Prometheus logo, the metrics tool you can use to monitor the Docker daemon state in production

Problems That Always Show Up

  • permission denied without sudo: the group change hasn’t applied to the session. newgrp docker fixes it.
  • Cannot connect to the Docker daemon: dockerd isn’t running. systemctl status docker and journalctl -u docker -n 100 reveal the cause.
  • Slow pulls: Docker Hub rate limits or DNS issues. A local registry-mirrors is the remedy.
  • Disk full: docker system prune -a --volumes frees space aggressively, including anonymous volumes — be careful.

Conclusion

What separates a viable install from one that will bite you in six months is not any command in the official repo, but the decisions you make right after. Configure log rotation from day one. Enable live-restore. Understand what the docker group implies. None of these shows up in five-minute tutorials, and all matter more than the exact order of the packages. If you plan to use the server with Docker Swarm, the next step is when Docker Swarm still makes sense.