DEV Community

Celso Nery
Celso Nery

Posted on

Installing Docker on Debian

#docker #debian #linux #devops

🇧🇷 Versão em português aqui

Installing Docker on Debian

Before running any container — whether for a standalone application or as a prerequisite for a Kubernetes cluster — you need the Docker Engine properly installed and configured on the server. This article covers the complete installation on Debian, from scratch to running your first container.

Use sudo before the commands below if you're running them as a regular user (not root).

Updating the system

Before installing any new package, update the package list and the system:

# apt update
# apt upgrade
Enter fullscreen mode Exit fullscreen mode

Installing required packages

A few packages are prerequisites for safely adding external repositories (GPG keys, HTTPS, etc.):

# apt install curl gnupg2 apt-transport-https software-properties-common ca-certificates
Enter fullscreen mode Exit fullscreen mode

Adding the Docker repository

Download and register Docker's official GPG key:

# curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/docker.gpg
Enter fullscreen mode Exit fullscreen mode

Create the repository file at /etc/apt/sources.list.d/docker.list:

deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/docker.gpg] https://download.docker.com/linux/debian bookworm stable
Enter fullscreen mode Exit fullscreen mode

⚠️ Watch your Debian version: the codename (bookworm, in the example) needs to match your Debian version — bookworm is Debian 12, bullseye is Debian 11, buster is Debian 10. To find out your installation's codename, run:

$ lsb_release -cs

And replace bookworm with the returned value, if you're on a different version.

Container runtime: Docker or containerd?

If the end goal is building a Kubernetes cluster, it's worth pausing here: Kubernetes hasn't used Docker directly as its runtime since version 1.24 — it relies on containerd (which, as it happens, already ships alongside the Docker Engine installation, but can also be installed standalone). If that's your case, skip straight to the Kubernetes installation article, which covers installing containerd specifically for that scenario.

If your goal is to use the full Docker Engine (to run standalone containers, Docker Compose, etc.), continue with the steps below.

Installing Docker 

# apt update
# apt install docker-ce
Enter fullscreen mode Exit fullscreen mode

If you run into issues running containers with the latest version, you can install a previous version known to be stable, such as 18.06.0:

# apt install docker-ce=18.06.0~ce~3-0~debian

Configuring the daemon

Create the /etc/docker/daemon.json file with the following settings:

{
    "exec-opts": ["native.cgroupdriver=systemd"],
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "100m"
        },
    "storage-driver": "overlay2"
}
Enter fullscreen mode Exit fullscreen mode

This configuration:

  • Uses systemd as the cgroup driver (important for staying consistent with other systemd-managed services on the system, including Kubernetes itself, if you install it later);
  • Limits each container's log size to 100MB, preventing "noisy" containers from filling up the disk with logs;
  • Uses the overlay2 storage driver, currently recommended for most use cases.

Create the Docker systemd service override directory:

# mkdir -p /etc/systemd/system/docker.service.d
Enter fullscreen mode Exit fullscreen mode

Reload and restart the service:

systemctl daemon-reload
systemctl restart docker
Enter fullscreen mode Exit fullscreen mode

Allowing a regular user to use Docker

By default, Docker commands require root privileges. To let a regular user run containers without needing sudo for every command, add them to the docker group:

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

You need to log out and log back in (or restart your session) for the group change to take effect.

Verifying the installation

Confirm Docker is installed and working:

$ docker version
Enter fullscreen mode Exit fullscreen mode

The output should look similar to this:

Client:
 Version:           18.06.0-ce
 API version:       1.38
 Go version:        go1.10.3
 Git commit:        0ffa825
 Built:             Wed Jul 18 19:09:33 2018
 OS/Arch:           linux/amd64
 Experimental:      false

Server:
 Engine:
  Version:          18.06.0-ce
  API version:      1.38 (minimum version 1.12)
  Go version:       go1.10.3
  Git commit:       0ffa825
  Built:            Wed Jul 18 19:07:38 2018
  OS/Arch:          linux/amd64
  Experimental:     false
Enter fullscreen mode Exit fullscreen mode

The version shown will vary depending on what's installed on your system — the example above reflects version 18.06.0.

Running your first container

The classic test, using Docker's official example image:

$ docker run hello-world
Enter fullscreen mode Exit fullscreen mode

Or, for a slightly more tangible test, spinning up an Apache web server (httpd) on port 80:

$ docker run --rm -p 80:80 httpd
Enter fullscreen mode Exit fullscreen mode

To confirm it worked, open your browser and access the host machine's IP:

http://127.0.0.1
Enter fullscreen mode Exit fullscreen mode

If Apache's default page shows up, the Docker installation is complete and working correctly.

Final thoughts

With Docker installed, configured with the correct cgroup driver, and successfully tested, the server is now ready both for running standalone containers day to day and for serving as a foundation for more advanced setups — such as Kubernetes itself, which reuses the containerd already present in this installation.

Top comments (0)