Lesson 1 - Installing Docker Desktop

Welcome to Installing Docker Desktop#

You’ve just joined CityFlow, a small mobility-analytics team whose public dashboard runs on New York City taxi data — the same dataset you worked with if you took the Python or PySpark courses in this path. Your job in this course is different from those: instead of analyzing the data, you’re going to make sure the pipeline that produces it runs identically no matter whose laptop, whose server, or whose Kubernetes cluster it lands on. That guarantee starts with a single piece of software: Docker Desktop.

This lesson has one goal — get Docker actually installed and actually working on your machine, and prove it with real output rather than trust. You won’t touch a line of “why containers matter” theory yet; that’s Lesson 2, once you have something real to compare it against. Right now, you’re installing a tool.

By the end of this lesson, you will be able to:

• Install Docker Desktop on your operating system, following Docker’s current official instructions.
• Explain, at a glance, what Docker Desktop actually installs (the CLI, the engine, and the lightweight VM that runs it).
• Verify the install with docker --version and a real docker run hello-world.
• Recognize Docker Desktop’s running state in its own interface.

You don’t need any programming experience for this lesson — just a computer with a few gigabytes of free disk space and an internet connection. Let’s install it.

Before you install: what you’re about to get#

Docker Desktop is a desktop application — a normal app you install like any other — but under the hood it sets up three distinct pieces:

1. The docker CLI. The command you’ll type in a terminal, on every operating system, from this lesson to the end of the course.
2. A lightweight Linux virtual machine. Containers are a Linux technology. On macOS and Windows, Docker Desktop quietly runs a small VM in the background so that docker run behaves identically whether you’re on a Mac, a Windows PC, or a Linux box. You will not manage this VM directly — Docker Desktop does it for you.
3. Docker Engine (dockerd), running inside that VM (or natively on Linux). This is the process that actually pulls images, builds them, and starts and stops your containers.

Knowing this shape matters later. When something goes wrong, you’ll know to ask “is the engine running?” rather than treating Docker as a black box.

Installing on macOS#

This step was verified firsthand on this pipeline’s own machine, an Apple Silicon Mac, following Docker’s current official documentation at docs.docker.com/desktop/setup/install/mac-install/.

Check your chip and macOS version#

Docker Desktop supports the current release of macOS plus the two previous major releases, and needs at least 4 GB of RAM. You also need to know which chip your Mac has:

• Apple Silicon (M1/M2/M3/M4) — look for “Apple” next to Chip in → About This Mac.
• Intel — look for “Intel” in the same panel.

Download and install#

1. Go to docker.com/products/docker-desktop/ and download the installer for your chip — Docker Desktop for Mac with Apple silicon or Docker Desktop for Mac with Intel chip. Downloading the wrong one is the single most common install mistake; the site detects your chip automatically, but it’s worth double-checking.
2. Double-click the downloaded Docker.dmg to open the installer, then drag the Docker icon into the Applications folder — the same drag-to-install pattern every Mac app uses.
3. Open Docker.app from Applications. On first launch, Docker Desktop shows its Subscription Service Agreement; select Accept to continue.
4. Choose the recommended settings (the default) unless you have a specific reason to customize them, then select Finish. macOS may prompt for your password once, to grant Docker the system privileges it needs.

Installing on Windows#

Windows steps are written from Docker’s current official documentation at docs.docker.com/desktop/setup/install/windows-install/ — this pipeline’s machine is a Mac, so these steps are sourced and labeled as documentation rather than independently verified firsthand.

Requirements#

Docker Desktop on Windows runs on the WSL 2 (Windows Subsystem for Linux) backend, which needs:

• Windows 11 64-bit (Enterprise, Pro, or Education, version 23H2/build 22631 or higher), or Windows 10 64-bit (version 22H2/build 19045).
• WSL version 2.1.5 or later.
• A 64-bit processor with SLAT, hardware virtualization enabled in your BIOS/UEFI, and at least 8 GB of RAM.

Download and install#

1. Download Docker Desktop Installer.exe from docker.com/products/docker-desktop/.
2. Double-click the installer. On the Configuration page, keep Use WSL 2 instead of Hyper-V selected — this is the recommended backend and what the rest of this course assumes.
3. Follow the wizard’s prompts to authorize the install, then select Close when it finishes.
4. Launch Docker Desktop from the Windows Start menu. On first launch, accept the Subscription Service Agreement.

If you prefer the command line, Docker also supports a silent per-user install with no administrator rights: "Docker Desktop Installer.exe" install --user.

Installing on Linux#

Linux steps are likewise sourced from Docker’s current official documentation at docs.docker.com/desktop/setup/install/linux/, labeled as documentation rather than independently verified on this pipeline’s Mac.

Docker Desktop for Linux supports Ubuntu, Debian, Fedora, RHEL, and (experimentally) Arch, and needs a 64-bit kernel with KVM virtualization support, systemd, and a supported desktop environment (GNOME, KDE, or MATE). On Ubuntu specifically, the install is a single .deb package:

sudo apt-get update
sudo apt install ./docker-desktop-amd64.deb

You may see a permission-related warning at the end of that command; Docker’s own documentation says it’s safe to ignore. Launch Docker Desktop from your application menu, or from a terminal with systemctl --user start docker-desktop, and accept the Subscription Service Agreement on first launch.

Verify it for real: docker --version#

Whichever platform you installed on, the first check is the same everywhere. Open a terminal and ask Docker to identify itself:

docker --version

Docker version 29.6.1, build 8900f1d

If you see a version string like this, the docker CLI is installed and can talk to the engine. If instead you get command not found, the install didn’t complete, or your terminal needs to be restarted to pick up the new PATH entry.

Verify it for real: run an actual container#

A version string only proves the CLI exists. To prove the whole stack — CLI, engine, and the ability to pull and run something — run Docker’s own tiny test image:

docker run hello-world

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
58dee6a49ef1: Pulling fs layer
58dee6a49ef1: Download complete
58dee6a49ef1: Pull complete
Digest: sha256:c3cbe1cc1aa588a64951ac6286e0df7b27fe2e6324b1001c619bb358770c0178
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm64v8)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

Read the first two lines carefully: Unable to find image 'hello-world:latest' locally, then Pulling from library/hello-world. That’s real, and it’s worth pausing on. You did not have this image five seconds ago. Docker’s engine noticed, reached out to Docker Hub — a public registry of images — downloaded a small image built specifically to prove an install works, and ran it as a container, all from one command. The four numbered steps in the output are Docker explaining, in plain English, exactly what it just did on your behalf.

Verify it for real: Docker Desktop’s own window#

The command line proves Docker works; Docker Desktop’s interface shows you the same information visually, which matters once you’re juggling several containers at once instead of reading raw text. Open the app and look at the Containers page.

Two details are worth knowing how to find on your own install: the “Engine running” indicator in the bottom-left corner (if it ever says anything else, docker commands will fail with a connection error), and the version number next to it, which should match — or be close to — what docker --version printed on the command line.

Practice Exercises#

Exercise 1: Confirm your own install#

On your own machine, run docker --version and docker run hello-world. Read the pull output line by line and identify which line tells you the image was not already present locally, and which line tells you the container actually ran.

Exercise 2: Watch the second run differ#

Run docker run hello-world a second time immediately after the first. Compare the two outputs line by line and write down, in your own words, what specifically was skipped the second time and why.

Exercise 3: Find the Engine status yourself#

Open Docker Desktop on your own machine and locate the running/stopped indicator for the engine (the same “Engine running” text this lesson’s screenshot shows). Note its exact wording and where it sits in the window.

Summary#

You installed Docker Desktop — following Docker’s own current documentation for your operating system — and, more importantly, you proved it actually works with real commands rather than trusting the installer. docker --version confirmed the CLI talks to the engine. docker run hello-world proved the full pull-then-run pipeline: Docker noticed the image was missing, pulled it from Docker Hub, created a container from it, and streamed the container’s output back to your terminal. You also saw Docker Desktop’s own Containers page and its “Engine running” indicator — the visual version of the same proof.

Key Concepts#

• Docker Desktop — the application that bundles the docker CLI, a lightweight Linux VM, and Docker Engine (dockerd) into one install, so containers behave the same way on macOS, Windows, and Linux.
• docker --version — confirms the CLI is installed and can reach the engine; the fastest first health check.
• docker run hello-world — a real end-to-end test: pull an image if it’s missing, create a container from it, run it, and print its output.
• Image vs. container, seen for the first time — the first docker run hello-world had to pull the image; the second one didn’t, because the image was already stored locally while the container itself is created fresh each time.

Why This Matters#

Every technique in the rest of this course — building images, running services, orchestrating them on Kubernetes — assumes you have a working Docker install and know how to prove it’s working when something breaks. “It’s not working” is a much easier problem to debug once you know it decomposes into three checkable pieces: is the engine running, does the CLI reach it, and does a known-good image (hello-world) run successfully. You now have all three checks in your hands.

Continue Building Your Skills#

Docker is installed and verified. But you still haven’t seen why it matters — only that it works. In Lesson 2, you’ll reproduce a real “works on my machine” bug: the exact same script, unmodified, failing on one Python installation and succeeding on another. Once you’ve felt that problem firsthand, Docker’s whole reason for existing stops being an abstraction and becomes something you’ve personally watched happen — and fixed.