🇧🇷 Artigo em português aqui

Docker for Devs — Part 1: Installing on Debian

This is the first part of a series on using Docker day to day: installation, CLI usage, volumes, networks, image management, and Docker Compose. The goal is to start from scratch and build up to a complete, professional workflow with Docker.

In this first part, we cover 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

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

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

Create the repository file at /etc/apt/sources.list.d/docker.list and add this content:

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

⚠️ 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

or

$ cat /etc/os-release

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

If you run into issues running containers with the latest version, you can install a previous version, 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"
}

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

Reload and restart the service:

systemctl daemon-reload
systemctl restart docker

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

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

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

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

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

$ docker run --rm -p 8080:80 httpd

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

http://127.0.0.1:8080

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

Next steps

With Docker installed, configured with the correct cgroup driver, and successfully tested, the server is now ready for day-to-day container work. In Part 2 of this series, we'll explore the most commonly used Docker CLI commands: run, ps, exec, stop, rm, logs, and stats.

Continued in Part 2.