Skip to main content

Docker Installation and Basic Configuration

This page only covers the Linux installation workflow I prefer to use by default, focusing on Ubuntu and other Debian-based distributions. The goal is not to cover every distribution, but to pin down the most common and reliable workflow first.

If you are not on Ubuntu, go directly to the official Docker installation documentation:

First, Remove Old Versions or Conflicting Packages​

If the machine has an older version of Docker installed, clean up common conflicting packages first before connecting to the official repository:

for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do
  sudo apt-get remove -y "$pkg"
done

Add the Official Docker apt Repository​

sudo apt-get update
sudo apt-get 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

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

This approach is more suitable for modern Ubuntu systems than the older apt-key method.

Install Docker Engine and Common Plugins​

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

This set of packages covers the capabilities I use daily:

  • docker-ce: Docker Engine
  • docker-ce-cli: The docker command line
  • containerd.io: The underlying container runtime
  • docker-buildx-plugin: More modern build capabilities
  • docker-compose-plugin: The docker compose command

Start and Verify Docker​

After installation, enable and start the service:

sudo systemctl enable --now docker

It is recommended to at least perform the following verification steps:

sudo systemctl status docker
docker version
docker info
docker compose version
sudo docker run --rm hello-world

If systemctl status docker shows active (running) and hello-world can be pulled and runs successfully, the basic installation is good.

Configure Non-root Users to Use Docker​

If you don't want to type sudo every time, you can add the current user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Log in again and test:

docker ps

Note: Adding a user to the docker group is essentially granting high-privilege control over the host's Docker, which is close to root in terms of security. On shared machines, multi-user machines, or production servers, don't add everyone by default.

If you explicitly want to avoid this, you can look at Docker's official rootless mode:

Common Follow-up Configuration​

1. Image Accelerator or Other Daemon Configuration​

The common configuration file path for the Docker daemon is:

/etc/docker/daemon.json

For example, when configuring an image accelerator, a common pattern is:

{
  "registry-mirrors": ["https://<your-mirror>.example.com"]
}

After making changes, restart Docker:

sudo systemctl restart docker

If you are on Alibaba Cloud and mainly experiencing slow or failed Docker Hub pulls, you can directly check this existing record:

2. Auto-start on Boot​

The enable --now used above already handles both "start now" and "auto-start on boot." To just confirm:

sudo systemctl is-enabled docker

What I Check First When Installation Fails​

If Docker won't start, don't rush to reinstall. Check these first:

  1. sudo systemctl status docker
  2. sudo journalctl -u docker.service -n 100 --no-pager
  3. Whether /etc/docker/daemon.json has invalid JSON
  4. Whether the machine can access Docker repositories or mirror sources
  5. Whether there are conflicts with older containerd or older mirror source configurations