Install Docker and Run Your First Container

In the previous post we covered what containers are and why Docker became the default tool for working with them. This guide is hands-on: by the end you will have a working Docker installation and a container you started, inspected, and removed yourself.

Pick the section that matches your operating system, install Docker, then continue from “Verify the installation.”

Step 1: Install Docker

One thing to know first. On Windows and macOS, you install Docker Desktop — a packaged application that includes the engine, a small Linux VM, and a GUI. On Linux, you install Docker Engine directly, since the host already has a Linux kernel.

On Windows

1. Visit docker.com/products/docker-desktop and download the installer for Windows.
2. Run Docker Desktop Installer.exe. Leave the default options ticked — in particular, “Use WSL 2 instead of Hyper-V” should remain selected. WSL 2 (Windows Subsystem for Linux) is what provides the Linux kernel containers need.
3. When prompted, sign out and back in (or reboot) so your user is added to the docker-users group.
4. Launch Docker Desktop from the Start Menu. The first run takes a minute while it initialises the WSL backend. Wait until the whale icon in the system tray stops animating.

If the installer reports that WSL is missing, open PowerShell as Administrator and run wsl --install, then reboot and try again.

On macOS

1. Visit docker.com/products/docker-desktop and download the installer.
2. Choose the correct build — Apple Silicon for M1/M2/M3/M4 Macs, Intel for older models. If you are unsure, click the Apple menu → About This Mac and check the Chip line.
3. Open the downloaded .dmg file and drag the Docker icon into Applications.
4. Launch Docker from Applications. Grant the permissions it asks for — it needs them to set up networking and the embedded Linux VM.
5. Wait for the whale icon in the menu bar to stop animating. When it shows “Docker Desktop is running,” you are ready.

On Linux

Linux users install Docker Engine from the official Docker repositories. The exact commands vary by distribution; the most common is Ubuntu/Debian:

# Remove any old versions
sudo apt remove docker docker-engine docker.io containerd runc

# Install prerequisites
sudo apt update
sudo apt install ca-certificates curl gnupg

# Add Docker's official GPG key and repository
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install the engine and Compose plugin
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

For Fedora, Arch, and others, follow the matching instructions at docs.docker.com/engine/install.

After installation, add your user to the docker group so you do not have to prefix every command with sudo:

sudo usermod -aG docker $USER
newgrp docker

Step 2: Verify the installation

Open a terminal (PowerShell on Windows, Terminal on macOS, your shell of choice on Linux) and run:

docker --version
docker compose version

You should see version numbers for both — something like Docker version 27.x.x and Docker Compose version v2.x.x. If both commands respond, the client is installed correctly.

Now verify that the engine is running and can pull and run an image:

docker run hello-world

The first time you run this, Docker will:

1. Notice that the hello-world image is not on your machine.
2. Pull it from Docker Hub (a few hundred kilobytes).
3. Create a container from it.
4. Run it. The container prints a confirmation message and exits.

If you see the message that begins with “Hello from Docker!”, everything works. If you see “Cannot connect to the Docker daemon,” the engine is not running — start Docker Desktop on Windows/macOS, or run sudo systemctl start docker on Linux.

Step 3: Run a real container

hello-world is a self-checking image; it is not very useful on its own. Let us run something with actual behaviour — the nginx web server:

docker run -d -p 8080:80 --name web nginx

Read that command carefully — every flag matters.

• docker run — create and start a container.
• -d — detached mode. Run the container in the background instead of attaching your terminal to it.
• -p 8080:80 — publish a port. Map port 8080 on your host to port 80 inside the container. The nginx process inside listens on 80; you reach it from your machine on 8080.
• --name web — give the container a friendly name. Without this, Docker invents one like eager_lovelace.
• nginx — the image to run. With no tag, Docker uses nginx:latest.

Open a browser and visit http://localhost:8080. You should see the default “Welcome to nginx!” page. A real web server is running on your machine, served by a container.

docker run -d -p 8081:80 --name web2 nginx

Step 4: Inspect what is running

Use these commands constantly while learning Docker.

# List running containers
docker ps

# List all containers, including stopped ones
docker ps -a

# Show the most recent log output from a container
docker logs web

# Follow the logs live (like tail -f)
docker logs -f web

# Open a shell inside the running container
docker exec -it web bash

docker exec -it web bash is particularly useful. The -i and -t flags together give you an interactive terminal inside the container’s filesystem. You can run ls, cat /etc/nginx/nginx.conf, or anything else as if you had SSH’d into a tiny Linux machine. Type exit to return to your host shell. The container keeps running.

Step 5: Stop and clean up

A running container costs memory and a small amount of CPU. When you are done, stop and remove it:

docker stop web
docker rm web

docker stop web2
docker rm web2

docker stop sends a polite shutdown signal and waits for the process to exit. docker rm deletes the stopped container. The image stays on your machine for next time.

To see the images you have downloaded:

docker images

To delete an image you no longer want:

docker rmi nginx

You cannot delete an image while any container (running or stopped) still references it — remove the containers first.

Common installation problems

A few errors are extremely common at this stage.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock The engine is not running. On Windows/macOS, launch Docker Desktop and wait for the whale icon to stop animating. On Linux, run sudo systemctl start docker and sudo systemctl enable docker so it starts automatically on boot.

permission denied while trying to connect to the Docker daemon socket (Linux) Your user is not in the docker group. Run sudo usermod -aG docker $USER, then log out and back in (or run newgrp docker).

port is already allocated Another process on your machine is using the host port you asked for. Either stop that process or pick a different port (-p 9090:80 instead of -p 8080:80).

Docker Desktop requires a newer WSL kernel version (Windows) Open PowerShell as Administrator and run wsl --update, then restart Docker Desktop.

Recap

You now have:

• A working Docker installation, verified with docker run hello-world
• A real container you started, inspected with docker ps and docker logs, and removed
• Practical familiarity with docker run, docker ps, docker exec, docker stop, and docker rm
• A clear mental model of host ports vs container ports, and detached vs foreground mode

Every later post in this series builds on these commands.

Next steps

The next post moves from running other people’s images to building your own. You will write a Dockerfile for a small application, build an image from it, and run that image as a container.

→ Next: Writing Your First Dockerfile

Questions or feedback? Email codeloomdevv@gmail.com.