A Guide to Docker Desktop

Docker Desktop is an all-in-one app for using Docker on a Mac, Windows or Linux computer. Made by Docker, Inc., it installs everything in one go: the engine that runs containers, the command-line tools, and a graphical dashboard.

A "container" is a box holding an app together with everything it needs to run: OS components, libraries, configuration. Because the whole box moves as one, it runs the same on anyone's laptop or on a server. The idea of containers itself is covered in the Dev Guide post Docker from the Basics to Practice. This article is about the app that brings Docker to your own computer.

• Docker Engine — the part that actually runs containers; the same engine used on Linux servers
• Command-line tools — docker, docker compose for running several containers together, docker buildx for building images, kubectl for Kubernetes, and more
• Dashboard — the screens shown in this article: lists of containers, images and volumes, the actions on them, logs, and settings
• Extras — single-node Kubernetes, Docker Scout for vulnerability checks, extensions, the AI assistant Gordon, Model Runner for running AI models, and others

Its predecessors were "Docker for Mac" and "Docker for Windows", which appeared in 2016. Before then, using Docker on a Mac or Windows PC meant setting up a virtual machine yourself. These apps made it work just by installing; they were later brought together under the name Docker Desktop, and a Linux version followed.

Containers rely on features of the Linux kernel (the core of the OS). The macOS and Windows kernels lack them, so Docker Desktop runs a small Linux virtual machine in the background and runs Docker Engine and your containers inside it.

Knowing this makes several things fall into place.

• It uses a lot of memory and disk — a whole Linux machine runs behind it. You can set limits (chapter 9)
• Reading and writing your own folders can be slow — files are passed between your computer and the virtual machine (chapter 13)
• You cannot reach a container's IP address directly — containers live on a network inside the virtual machine. To use them from outside, publish a port (chapter 3)
• Intel images are slow on Apple silicon Macs — the virtual machine runs ARM Linux, so images built for Intel (amd64) have to run under emulation

Before touching the screens, let us pin down Docker's vocabulary. Once these words are clear, where things sit on screen becomes obvious too.

The most important instinct is that containers are disposable. Anything written inside a container disappears when the container is deleted. Data you want to keep goes in a volume or a bind mount. Chapter 8 returns to this distinction.

Download Docker Desktop from the official site (docker.com). For the Mac there are separate downloads for Apple silicon and Intel.

The part to watch is the price. Docker Desktop is not free for everyone.

Signing in is not required. The screenshots in this article were taken on Personal without signing in ("PERSONAL" appears at top left). Signing in has benefits, such as looser rate limits when pulling images from Docker Hub.

Launch it and the window below (the dashboard) opens. You can also open it at any time from the whale icon in the menu bar.

Let us start by running the web server nginx ("engine-x"), without typing a single command.

After Run, the container starts as soon as the image has downloaded, and the view switches to the container's detail screen (the photo at the top). Opening http://localhost:8080 in a browser showed the "Welcome to nginx!" page, confirming that port 8080 on the computer is now connected to port 80 in the container.

Running containers appear on the Containers screen. This Mac has other containers too, so the list is filtered by name with the search box.

A container has a life cycle. Here is how the buttons and the commands relate to it.

Click a container's name to open its detail screen. This is the screen you will use most in Docker Desktop.

Pulled images are listed on the Images screen. A single image can run to hundreds of megabytes, and letting them pile up eats your disk. Delete the ones you no longer use from here.

Docker Scout's analysis builds a list of the packages in the image (an SBOM) and matches it against known vulnerabilities. "Has vulnerabilities" does not mean "dangerous right now", but items marked "Fixable" can often be cleared by switching to a newer image, so a regular look is reassuring.

Next, where data lives. The figure sums up the three places.

Attaching a volume made on screen to a container is done with a command (docker run -v) or in a Compose file. It helps to think of the screen as the place to list volumes, look inside them, and delete the ones you no longer need.

Open Settings from the gear at top right. The first page worth a look is Resources.

The Docker Engine page is for advanced users. Here you write settings such as a registry mirror (an alternative download source) or a cap on log file size. Keep a copy of the original before editing so you can restore it quickly if the engine stops starting.

Everything the screens do can also be done with commands. Learn on screen first, then move to commands as you get comfortable; commands are easy to record in documents and scripts. Here is everything so far as commands.

# (1) Pull the image (Pull on screen)
docker pull nginx:stable-alpine

# (2) Start it with a name and a port (Run on screen)
docker run -d --name kiji-web -p 8080:80 nginx:stable-alpine

# (3) List containers (Containers screen; -a includes stopped ones)
docker ps -a

# (4) Read the logs (Logs tab; -f follows new lines)
docker logs -f kiji-web

# (5) Go inside (Exec tab)
docker exec -it kiji-web sh

# (6) Create a volume (Create on the Volumes screen)
docker volume create kijidata

# (7) Clean up (the delete buttons)
docker rm -f kiji-web
docker volume rm kijidata
docker image rm nginx:stable-alpine

# (8) See disk usage, and clear out what is unused
docker system df
docker system prune

To combine several containers, use Compose (see chapter 6 onwards of Docker from the Basics to Practice). Containers started with docker compose up are grouped under the project name on the Containers screen, so you can stop or delete them together.

Over the past year or two, Docker Desktop has gained a run of AI-related features. Here they are, from the top of the left menu.

All of these are new, many are in beta, and their screens and names change often. When you let Gordon read a project folder, remember that its contents are sent to an AI service, and check beforehand whether that is allowed for company code. For running AI models locally, the Dev Guide post Running Large Models Locally may also help.

Docker Desktop is not the only app that runs containers locally. They all use the same image format (OCI), so switching later is not hard.

On Windows you can also install the Linux Docker Engine directly inside WSL 2. It is free, but you have to sort out the integration with Windows (file sharing, starting it up) yourself.

• Clean the disk regularly — images, stopped containers, unused volumes and build cache all pile up. See the breakdown with docker system df and clean up with docker system prune (volumes are removed only if you add --volumes)
• Choose ARM images on Apple silicon Macs — most official images contain both and the right one is picked automatically. Intel-only images run with --platform linux/amd64, but slowly
• When shared source code is slow — put masses of small files such as node_modules in a volume. The paid plans' Synchronized file shares are another option
• Calling services on your computer from a container — use host.docker.internal, not localhost. Inside a container, localhost means the container itself
• If you see "port is already allocated" — another app or container is using that port. Change the number (say 8081:80) or stop whatever is using it
• When it will not start or misbehaves — from the "?" (Troubleshoot) at top right, try "Restart" first. If that fails, gather diagnostics (also possible with docker desktop diagnose)
• Only trusted extensions — the settings screen itself warns that extensions run with host privileges. They can read and write files and control Docker Engine, so check where one comes from before installing it
• Keep versions in step — in a team, align Docker Desktop and Compose versions, and write the versions into your setup guide