DEV Community

Cover image for Installing Docker on Debian
serverkueche.de
serverkueche.de

Posted on Originally published at serverkueche.de

Installing Docker on Debian

#tutorial #docker #linux

Docker is the foundation for almost every application tutorial in the Serverküche. We install it from the official Docker repository – not from the Debian package sources.

What are we building?

By the end, the current Docker Engine with the Compose plugin runs on your Debian 13, installed from the official Docker repository. That has two advantages over the Debian package docker.io: more current versions with timely security updates, and the official docker compose that all Compose recipes here build on.

Prerequisites

Step by step

Step 1: Set up the repository key

First, install the tools needed to verify the Docker repository:

sudo apt update
sudo apt install -y ca-certificates curl
Enter fullscreen mode Exit fullscreen mode

Then create the keyring directory and download Docker's GPG key – apt uses it later to check that the packages really come from Docker:

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
Enter fullscreen mode Exit fullscreen mode

Step 2: Add the Docker package source

Add the Docker repository to your package sources. The command detects the architecture and Debian version automatically, so you can copy it unchanged:

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
Enter fullscreen mode Exit fullscreen mode

Step 3: Install Docker

Refresh the package lists (now including the Docker repository) and install the Engine together with the Compose plugin:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Enter fullscreen mode Exit fullscreen mode

Check that the service is running:

sudo systemctl status docker
Enter fullscreen mode Exit fullscreen mode

You should see active (running). A quick smoke test:

sudo docker run --rm hello-world
Enter fullscreen mode Exit fullscreen mode

The output Hello from Docker! confirms that the installation works.

Finally, check which versions actually got installed – that's the information every bug report will ask you for:

docker --version
docker compose version
Enter fullscreen mode Exit fullscreen mode 
Docker version 29.7.2, build a7dcaa6
Docker Compose version v5.4.0
Enter fullscreen mode Exit fullscreen mode

The exact patch numbers keep moving; what matters is that the Engine is on 29.x and Compose on v5.x – that's what the Compose recipes here build on.

Step 4: Use Docker without sudo

Add your user to the docker group so you don't have to prefix every command with sudo:

sudo usermod -aG docker $USER
Enter fullscreen mode Exit fullscreen mode

💡 Tip

The group membership only takes effect after you log out and back in (end the SSH session and reconnect).

⚠️ Security note

Members of the docker group effectively have root rights on the server – only add your own admin user, no shared or unprivileged accounts.

After that, docker ps works without sudo and shows a (still empty) container list.

When things go wrong

E: Package 'docker-ce' has no installation candidate. The package source from step 2 is missing or malformed – apt only knows the name from the Debian packages' dependencies and finds no package behind it. Check the contents of /etc/apt/sources.list.d/docker.list – it must contain your Debian version (e.g. trixie) – and then run sudo apt update again.

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock. The docker group membership hasn't taken effect yet. End the SSH session and reconnect; groups must then include docker. If not, repeat step 4.

Conflicts during installation with already-present packages. Another Docker variant is already installed (docker.io, podman-docker, …). Remove the old packages first: sudo apt remove docker.io docker-doc docker-compose podman-docker containerd runc – existing containers/images are preserved.

docker compose reports docker: unknown command: docker compose. The Compose plugin is missing – Docker was probably installed differently earlier. Run sudo apt install docker-compose-plugin. Note: the old docker-compose (with a hyphen) is a different, outdated tool.

Maintenance & backups

  • Updates: Docker updates along with the normal sudo apt update && sudo apt upgrade – one reason we use the official repository. When the Engine is updated, running containers restart briefly (or stop until you start them again) – plan for that.
  • Cleanup: Unused images and build leftovers pile up quickly. docker system df shows the usage, docker system prune cleans up (careful: it also removes stopped containers).
  • Backups: The actual data of your applications will later live in volumes or bind mounts – we build the backup strategy for that with encrypted Restic backups and in the individual application tutorials.

This post first appeared on serverkueche.de.

Top comments (0)