Lesson 04 beginner

Installing Docker

Install Docker Engine on Ubuntu and Rocky Linux from the official repositories, set up Docker Desktop on macOS and Windows, and fix the two errors everyone hits first.

There are two ways to get Docker. On Linux servers you install Docker Engine directly. On macOS and Windows you install Docker Desktop, which bundles the engine inside a small Linux virtual machine plus a graphical dashboard. Both give you the same docker command.

Ubuntu and Debian

Use Docker’s own apt repository rather than the distribution’s docker.io package, which is often several versions behind. First remove any old packages, then add the repository key and source:

$ for pkg in docker.io docker-compose podman-docker containerd runc; do sudo apt-get remove -y $pkg; done
$ 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 "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Then install the engine, the CLI and the Buildx and Compose plugins:

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

On Debian, replace ubuntu with debian in both URLs.

Rocky Linux, AlmaLinux and RHEL

$ sudo dnf -y install dnf-plugins-core
$ sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
$ sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
$ sudo systemctl enable --now docker

On Fedora, use the fedora repository URL instead of rhel. Ubuntu starts the service automatically; on RHEL-based systems the last command starts it now and at every boot.

Shortcut for test machines: curl -fsSL https://get.docker.com | sh installs everything in one step. It is handy for throwaway VMs, but on production servers prefer the explicit steps above so you know exactly what was configured.

Run Docker without sudo

By default only root can talk to the Docker daemon. Add your user to the docker group, then start a new login session (or run newgrp docker):

$ sudo usermod -aG docker $USER
$ newgrp docker
$ docker ps
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Security note: members of the docker group can start a container that mounts the host filesystem, so the group is effectively root. Only add trusted users. For stricter setups, look at rootless mode, where the daemon itself runs as your user (dockerd-rootless-setuptool.sh install).

macOS and Windows: Docker Desktop

  1. Download Docker Desktop from the official Docker website for your platform (Apple silicon or Intel for macOS).
  2. On Windows, make sure WSL 2 is installed first: open PowerShell as administrator and run wsl --install, then restart.
  3. Run the installer, start Docker Desktop and wait until the whale icon says the engine is running.

The docker and docker compose commands are then available in Terminal, PowerShell and inside your WSL distributions.

Verify the installation

$ docker version --format 'Client {{.Client.Version}} / Server {{.Server.Version}}'
Client 28.5.1 / Server 28.5.1
$ docker compose version
Docker Compose version v2.40.0
$ docker run --rm hello-world | head -2

Hello from Docker!

If you see both a client and a server version, the CLI can reach the engine and you are ready.

Fix the two most common errors

Permission denied on docker.sock

$ docker ps
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

Your user is not in the docker group yet, or you added it but did not log in again. Run groups to check, then log out and back in. Using sudo docker also works.

Cannot connect to the Docker daemon

$ docker ps
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
$ sudo systemctl status docker --no-pager | head -3
○ docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; disabled)
     Active: inactive (dead)
$ sudo systemctl enable --now docker

The service is installed but not running. On Docker Desktop, the equivalent fix is to start the Docker Desktop app.

Exercise

docker ps fails with “Cannot connect to the Docker daemon at unix:///var/run/docker.sock”. Your user is already in the docker group. What do you check first?

  1. Whether the Docker service is running, with systemctl status docker
  2. Whether the docker CLI needs to be reinstalled
  3. Whether you must add your user to the group again
  4. Whether you should switch to Docker Desktop
Show answer

Answer: A. This error means the CLI found nobody listening on the socket. Start the daemon and make it start on boot with sudo systemctl enable --now docker.

Key takeaways

  • Install Docker Engine from Docker’s official repository on Linux, and Docker Desktop on macOS and Windows.
  • The docker group lets you skip sudo, but it is equivalent to root access.
  • docker version must show both a client and a server to confirm the engine is reachable.
  • “Permission denied” means a group problem; “cannot connect” means the service is not running.

FAQ

Should I install the docker.io package from my distribution?

It works, but it usually lags behind Docker’s releases and misses the Compose and Buildx plugins. The official repository gets security fixes first.

Is Podman a replacement for Docker?

Podman runs the same OCI images with a largely compatible command line and runs rootless by default. Everything in this course works with Podman with small differences, but the examples use Docker.

Do I need Docker Desktop on a Linux server?

No. Docker Desktop is meant for workstations. Servers only need Docker Engine and the CLI plugins installed above.

↑ ↓ navigate Enter open Esc close