Install Docker Engine on Ubuntu and Debian

Most DockLog installs assume Docker Engine is already running on the host. If you are on a fresh Ubuntu or Debian VPS, this post follows the official Docker documentation so you do not end up with the wrong docker.io package from distro repos.

Sources: Install Docker Engine, Ubuntu, Debian, Linux post-install.

Before you install

Pick your path

This post covers the apt repository method on Ubuntu and Debian. Steps are nearly identical; only the GPG key URL and repository URI differ.

Supported versions (check yours)

Ubuntu (64-bit): Noble 24.04 LTS, Jammy 22.04 LTS, and newer releases listed in the Ubuntu install doc.

Debian: Trixie 13, Bookworm 12, Bullseye 11 per the Debian install doc.

Derivatives (Mint, Kali, etc.) may work but are not officially tested. Match the underlying Ubuntu or Debian codename when in doubt.

Firewall note from Docker docs

If you use ufw or firewalld, published container ports bypass some host firewall rules. Docker expects iptables-nft or iptables-legacy. Rules built with nft alone are not supported. Read Docker and ufw before exposing services on a locked-down VPS.

Step 1: Remove conflicting packages

Docker's docs require removing unofficial packages before installing docker-ce:

sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc 2>/dev/null | cut -f1)

apt may report none are installed. That is fine.

Data under /var/lib/docker/ is not removed by uninstall. Wipe it only if you want a truly clean slate (see uninstall section in the official docs).

Step 2: Set up Docker's apt repository

On Ubuntu

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

On Debian

Same flow, different GPG URL and URI:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

On Debian testing or derivatives, if VERSION_CODENAME is wrong, substitute the stable Debian codename (for example bookworm) manually. The official Debian page calls this out explicitly.

Step 3: Install Docker Engine packages

Latest stable (recommended for most VPS hosts):

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

That single line installs Engine, CLI, containerd, Buildx, and the Compose plugin. You do not need a separate Compose install post if this succeeds.

Pin a specific version when you need reproducible servers:

apt list --all-versions docker-ce
VERSION_STRING=5:29.6.0-1~ubuntu.24.04~noble   # example; pick from apt output
sudo apt install -y docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-buildx-plugin docker-compose-plugin

Adjust the version string for your distro and architecture per apt list output.

Step 4: Verify the daemon

sudo systemctl status docker

Start manually if needed:

sudo systemctl start docker

Run the official smoke test image:

sudo docker run hello-world

You should see a short confirmation message from the container, then it exits.

Check versions:

docker version
docker compose version

Step 5: Post-install (non-root user)

Official docs: without this step, every command needs sudo.

sudo groupadd docker 2>/dev/null || true
sudo usermod -aG docker $USER
newgrp docker
docker run hello-world

The docker group grants root-equivalent access to the daemon. Read Docker daemon attack surface before adding contractors.

If you previously ran sudo docker and see permission errors on ~/.docker/config.json, fix ownership per the post-install doc:

sudo chown "$USER":"$USER" "$HOME/.docker" -R
sudo chmod g+rwx "$HOME/.docker" -R

Start on boot

On Ubuntu and Debian, Docker usually starts on boot already. For other systemd distros:

sudo systemctl enable docker.service
sudo systemctl enable containerd.service

Log rotation (easy to skip, painful later)

Default json-file logs grow until disk fills. Docker documents rotation in the logging drivers page. Set max-size and max-file in compose before production traffic. Our log management guide walks through it.

Convenience script (dev only)

Docker publishes https://get.docker.com/ for non-interactive installs. Official docs warn: not for production, may upgrade major versions unexpectedly, not designed to upgrade existing installs cleanly. Preview with:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh ./get-docker.sh --dry-run

For a VPS you will keep for years, prefer the apt repository steps above.

Troubleshooting

What to do next

1. Install or verify Docker Compose if docker compose version failed
2. Compose file for DockLog production
3. Health checks and log rotation before you expose apps
4. Self-hosted monitoring map when the host is more than a toy project

Official upgrade path: run sudo apt update and reinstall docker-ce packages from the same repository. Test on staging before rolling prod.