Docker Setup

Debian / Ubuntu

Overview

Install Docker and complete initial configuration.

Assumptions

• Initial System Setup completed.

• Logged in as administrative user.

Update

Before getting started, update package repositories and apply upgrades for the latest patches.

# Debian
sudo apt update
sudo apt upgrade

Installation

Install Docker from the official Docker package repositories.

Uninstall Conflicting Packages

For a fresh install of Docker on a system, uninstall potentially conflicting or outdated packages. Consider using purge instead of remove to remove associated files.

Remove Docker-bundled dependency conflicts and alternative Docker packages provided by distribution maintainers.

sudo apt remove docker.io docker-doc docker-compose podman-docker containerd

Remove old Docker versions and packages.

sudo apt remove docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras

Optionally, delete existing Docker containers, images, and volumes.

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

Add Docker Repository

Create a directory to store apt keys, if not already present.

sudo install -m 0755 -d /etc/apt/keyrings

Download the Docker GPG key to the keyrings directory.

sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc

Add the Docker repository to the apt sources list.

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

Update package repositories to use the new source.

sudo apt update

Install Docker

Install the Docker platform packages.

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

Test that Docker is operating with the hello-world image.

sudo docker run hello-world

Enable Docker

Enable the docker and containerd services, to start on boot, with systemd.

sudo systemctl enable docker.service

sudo systemctl enable containerd.service

Docker Group

Create a docker group, on some distributions it is not created during installation. To check if the group exists manually, use command getent group docker.

sudo groupadd docker

Add the administrative user to the docker group so it can execute Docker commands without sudo.

sudo usermod -aG docker $USER

Logout and log back in to the user account. Run the hello-world image again, this time without the sudo prefix.

docker run hello-world

Logging Driver

Docker uses JSON logging by default for backward compatibility. Switch to the default logging driver to local for pre-configured log-rotation and to prevent disk-exhaustion. Refer to the Docker logging drivers documentation to make your log format choice.

Create or modify the Docker daemon.json configuration file.

sudo nano /etc/docker/daemon.json

Add the log driver configuration.

{
  "log-driver": "local",
  "log-opts": {
    "max-size": "10m"
  }
}

Rootless

Docker can be configured to run as a non-root user, this is optional. Do not run any applications on ports below 1024 in rootless mode, it will not work.

Install rootless dependencies.

sudo apt install uidmap dbus-user-session fuse-overlayfs slirp4netns

Docker Daemon User

Create a new system user, dockerdaemon, for the Docker daemon to run under.

sudo useradd --system --user-group --create-home --home /opt/dockerdaemon --shell /bin/bash dockerdaemon

The dockerdaemon user requires at least 65,536 UIDs and GIDs. Grant these IDs using uidmap.

sudo sh -eux <<EOF
echo "dockerdaemon:300000:65536" >> /etc/subuid
echo "dockerdaemon:300000:65536" >> /etc/subgid
EOF

MachineCTL Shell

Due to the challenges presented by the setup script, documented in issue #14491, the new user cannot be utilized via su or sudo.

To run the setup script as the dockerdaemon user, you must login directly on the system, SSH into the system as the user, or use machinectl to run the setup script and control the Docker service. This guide will take the machinectl route to avoid granting SSH access to a user that shouldn’t have SSH access.

Install the systemd-container package to use the machinectl tool. These should be removed when setup is complete.

sudo apt install systemd-container libnss-mymachines

Open a new shell session with machinectl as the dockerdaemon user.

machinectl shell --uid=dockerdaemon

Run Rootless Setup Tool

Within the machinectl shell as the dockerdaemon user, run the following setup commands in this section.

/usr/bin/dockerd-rootless-setuptool.sh install

At the end of setup, a notification for creating a DOCKER_HOST variable will be presented. Note the number after user, most likley 999 or 1000.

[INFO] Installed docker.service successfully.
...
[INFO] Some applications may require the following environment variable too:
export DOCKER_HOST=unix:///run/user/999/docker.sock

Open the dockerdaemon user’s .bashrc file.

nano /opt/dockerdaemon/.bashrc

Use the export statement for DOCKER_HOST provided by the setup script in the following command to add it to the .bashrc file for dockerdaemon user. Make sure the 999 is correct.

# Docker
export DOCKER_HOST=unix:///run/user/999/docker.sock

Close the machinectl session as the dockerdaemon user.

exit

Remove MachineCTL

With rootless setup complete, remove the systemd-container packages.

sudo apt purge systemd-container libnss-mymachines

Enable Docker Daemon

Enable the Docker service, now rootless, to start at boot.

sudo systemctl --user -M dockerdaemon@ enable docker

sudo loginctl enable-linger dockerdaemon

Usage

Check the status of the Docker service.

sudo systemctl --user -M dockerdaemon@ status docker

Start or stop the Docker service.

sudo systemctl --user -M dockerdaemon@  start docker
sudo systemctl --user -M dockerdaemon@  enable docker

Errors

Rootless uidmap

If there are not enough UIDs and GIDs assigned to the rootless user when running the setup script, the following error will be encountered.

Verify the rootless user has enough UIDs and GIDs. Don’t overlap with already used ranges.

[ERROR] Missing system requirements. Run the following commands to
[ERROR] install the requirements and run this tool again.

########## BEGIN ##########
sudo sh -eux <<EOF
# Add subuid entry for dockerdaemon
echo "dockerdaemon:100000:65536" >> /etc/subuid
# Add subgid entry for dockerdaemon
echo "dockerdaemon:100000:65536" >> /etc/subgid
EOF
########## END ##########

Rootless systemd

When running the setup script for Docker rootless via su or sudo, the command systemctl --user will fail during setup causing the following error.

Solve this by logging into the Docker rootless user using the MachineCTL shell.

# WARNING: systemd not found. You have to remove XDG_RUNTIME_DIR manually on every logout.
export XDG_RUNTIME_DIR=/opt/dockerdaemon/.docker/run

References

^{1 2}