How to Install Docker on Debian 13 - Complete Rootless Setup Guide

, , , , , , , ,

Installing Docker on Debian 13 (Trixie) is straightforward, but configuring it to run without root privileges requires additional steps. This comprehensive guide walks you through both the standard installation and the rootless mode, which significantly improves security by eliminating the need for sudo access.

Why Run Docker Without Root?

Running Docker as the root user poses significant security risks. If a container is compromised, the attacker gains root access to your host system. Rootless Docker allows you to:

  • Run containers as an unprivileged user
  • Reduce the attack surface
  • Follow the principle of least privilege
  • Deploy containers in multi-user environments safely

Prerequisites

Before starting, ensure you have:

  • Debian 13 (Trixie) installed and updated
  • A non-root user with sudo privileges
  • At least 2GB of RAM
  • Stable internet connection

Step 1: Update Your System

Always begin by updating your package list and installed packages:

1
sudo apt update && sudo apt upgrade -y

Step 2: Install Required Dependencies

Docker requires several packages to function properly:

1
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

These packages enable secure communication with Docker’s repository.

Step 3: Add Docker’s Official GPG Key

Import Docker’s GPG key to verify package authenticity:

1
2
3
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

Step 4: Add Docker Repository

Add Docker’s official repository to your APT sources:

1
2
3
4
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

Update the package index after adding the repository:

1
sudo apt update

Step 5: Install Docker Engine

Now install Docker Engine, CLI, and containerd:

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

Verify the installation:

1
2
sudo docker --version
sudo docker compose version

Step 6: Add User to Docker Group (Traditional Method)

To run Docker without typing sudo for each command, add your user to the docker group:

1
sudo usermod -aG docker $USER

Important: Log out and log back in (or reboot) for the group changes to take effect:

1
newgrp docker

Test the configuration:

1
docker run hello-world

While the docker group method works, it still grants users root-equivalent privileges. The rootless mode provides true isolation without root access.

7.1 Verify Prerequisites

Check if user namespaces are enabled:

1
cat /proc/sys/kernel/unprivileged_userns_clone

If this returns 0, enable it:

1
2
echo "kernel.unprivileged_userns_clone = 1" | sudo tee /etc/sysctl.d/99-rootless.conf
sudo sysctl --system

7.2 Install Docker Rootless Prerequisites

Install uidmap for user namespace mapping:

1
sudo apt install -y uidmap

7.3 Install Rootless Docker

Download and install the rootless Docker daemon:

1
dockerd-rootless-setuptool.sh install

If the command is not found, run the installer script:

1
curl -fsSL https://get.docker.com/rootless | sh

7.4 Configure Environment Variables

Add these environment variables to your shell configuration:

1
2
3
echo 'export PATH=$HOME/bin:$PATH' >> ~/.bashrc
echo 'export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock' >> ~/.bashrc
source ~/.bashrc

For systemd systems, Docker creates a user service. Enable it to start automatically:

1
2
3
systemctl --user enable docker
systemctl --user start docker
systemctl --user status docker

7.5 Verify Rootless Installation

Check if Docker is running without root:

1
docker run hello-world

Confirm the container runs as your user:

1
ps aux | grep docker

You should see the daemon running under your username, not root.

Step 8: Configure Docker Compose for Rootless Mode

Docker Compose works seamlessly with rootless Docker. Create a sample project:

1
mkdir ~/docker-projects && cd ~/docker-projects

Create a docker-compose.yml file:

1
2
3
4
5
6
7
8
9
10
11
12
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped

volumes:
  html:

Create the HTML directory:

1
2
mkdir -p html
echo "<h1>Rootless Docker on Debian 13 works!</h1>" > html/index.html

Start the container:

1
docker compose up -d

Access the site at http://localhost:8080

Step 9: Persistent Storage Configuration

Rootless Docker stores data in your home directory. Configure persistent storage:

1
mkdir -p ~/.local/share/docker/volumes

Update your compose files to use named volumes:

1
2
3
volumes:
  mydata:
    driver: local

Step 10: Networking in Rootless Mode

Rootless Docker has networking limitations. To bind to privileged ports (<1024), use:

1
sudo apt install -y libpam-cap

Or configure your application to use non-privileged ports (8080, 3000, etc.).

Step 11: Troubleshooting Common Issues

Issue: “Cannot connect to Docker daemon”

Solution: Ensure the environment variables are set:

1
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/docker.sock

Issue: Permission denied on volumes

Solution: Ensure your user owns the host directories:

1
chown -R $(id -u):$(id -g) /path/to/volume

Issue: Port already in use

Solution: Check for conflicts:

1
netstat -tlnp | grep :80

Issue: Container fails to start

Solution: Check logs:

1
2
docker logs container_name
docker-compose logs -f

Step 12: Updating Docker

Keep Docker updated regularly:

1
2
sudo apt update
sudo apt upgrade -y

For rootless mode, reinstall if major updates occur:

1
2
dockerd-rootless-setuptool.sh uninstall
dockerd-rootless-setuptool.sh install

Security Best Practices

  1. Regular Updates: Keep your system and Docker updated
  2. Image Scanning: Use docker scan to check for vulnerabilities
  3. Resource Limits: Set CPU and memory limits for containers
  4. Read-only Filesystems: Run containers with read-only root where possible:
1
docker run --read-only --tmpfs /tmp:rw,noexec,nosuid,size=100m nginx:alpine
  1. Drop Capabilities: Remove unnecessary Linux capabilities:
1
docker run --cap-drop=ALL --cap-add=CHOWN nginx:alpine

Uninstallation

If you need to remove Docker:

1
2
3
4
sudo apt purge -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo rm -rf /var/lib/docker
sudo rm -rf /etc/apt/sources.list.d/docker.list
sudo rm -f /etc/apt/keyrings/docker.gpg

For rootless mode:

1
2
dockerd-rootless-setuptool.sh uninstall
rm -rf ~/.local/share/docker

Conclusion

Running Docker without root privileges on Debian 13 significantly enhances your