Common Errors, Fixes, and What Actually Happens When You Run hello-world
Okay, so you've heard about Docker. Maybe your professor mentioned it, or someone in a YouTube comment said "just use Docker, bro" and walked away like that explained anything. Either way, you're here now, and we're going to get you set up — properly.
This isn't going to be a dry documentation dump. By the end of this, you'll have Docker installed, you'll understand what you just installed, and you'll know what to do when things inevitably go sideways. Because they will. That's just Tuesday in software.
First, What Even Is Docker? (The Quick Version)
Before we install anything, let's make sure we're on the same page about what Docker actually does — because installing software you don't understand is how you end up with six mystery programs running on your machine.
Think of it this way. You've probably had this experience: you write some code, it works perfectly on your laptop, you send it to your teammate, and it explodes on their machine. "But it works on mine," you say, staring into the void.
Docker fixes that. It wraps your application in a container — a self-contained box that includes your app and everything it needs to run: the right version of Python, the right libraries, the right environment variables, all of it. The container runs the same way everywhere. On your laptop, on your friend's laptop, on a server in Frankfurt. Doesn't matter.
The analogy people use is shipping containers, and it's actually a good one. Before shipping containers existed, loading a ship was chaos — different sizes, different packing methods, nobody knew where anything was. Shipping containers standardized everything. One standard box that fits on any ship, any truck, any crane. Docker does that for software.
Now, let's install it.
Installing Docker on Windows
Windows has a couple of ways to run Docker, but the right way for most people in 2024 is Docker Desktop. It's a GUI application that also installs the Docker engine and CLI tools you need.
What You Need First
Docker on Windows requires something called WSL 2 (Windows Subsystem for Linux 2). This is basically a real Linux kernel running inside Windows. Docker needs it to run Linux containers, which is what most Docker images are built on.
Here's how to check if you have it:
wsl --version
Run that in PowerShell. If you get a version number back, you're good. If you get an error, open PowerShell as Administrator and run:
wsl --install
This installs WSL 2 and Ubuntu. Restart your machine when it's done.
Downloading and Installing Docker Desktop
- Go to https://www.docker.com/products/docker-desktop
- Click the download button for Windows
- Run the installer (
Docker Desktop Installer.exe)
- During installation, make sure "Use WSL 2 instead of Hyper-V" is checked
- Let it do its thing, then restart
After restart, Docker Desktop will launch on its own. Give it a minute — the little whale icon in your system tray will animate while Docker is starting up. Once it's still, Docker is running.
Verify the Installation
Open PowerShell or Command Prompt and run:
docker --version
You should see something like Docker version 25.0.3, build 4debf41. The exact numbers don't matter — any output here means Docker CLI is working.
Installing Docker on Mac
Mac has its quirks, mostly because Apple switched to Apple Silicon (M1, M2, M3 chips) a few years ago and some older Docker images don't support it natively. But Docker Desktop handles this gracefully now with something called Rosetta emulation, so it mostly just works.
Download Docker Desktop for Mac
- Head to https://www.docker.com/products/docker-desktop
- Pay attention here: there are two versions — one for Intel chips and one for Apple Silicon. Click the Apple menu → About This Mac to see which you have
- Download the right
.dmg file
- Open it and drag Docker to your Applications folder
Starting Docker
Launch Docker from your Applications folder like any other app. The first time it starts, it'll ask for your password (it needs admin rights to set up the virtual machine it runs containers in). Give it a minute to finish the initial setup.
You'll see the Docker whale icon appear in your menu bar. When it stops animating, Docker is ready.
Verify It's Working
Open Terminal and run:
docker --version
docker ps
docker ps lists running containers. Right now it'll show an empty table, which is correct — we haven't started anything yet.
Installing Docker on Linux
This is actually the most straightforward install once you know the right way to do it. The wrong way is running sudo apt install docker.io — that'll install an outdated version from Ubuntu's package repositories. The right way pulls directly from Docker's official repo.
The instructions below are for Ubuntu/Debian. Other distros have similar processes.
Step 1: Remove Old Versions
If you've ever tried to install Docker before, clean that up first:
sudo apt-get remove docker docker-engine docker.io containerd runc
Even if those aren't installed, this command won't throw an error — it'll just skip what it can't find.
Step 2: Set Up Docker's Repository
# Update package index
sudo apt-get update
# Install packages needed to add a repo over HTTPS
sudo apt-get install ca-certificates curl gnupg
# Add Docker's official GPG key (this verifies the packages are legit)
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
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# Add the Docker repository to your sources
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
I know that looks like a lot. But you're basically just telling your system "hey, go look in Docker's official repo when I ask for Docker packages." Each command is doing one small, sensible thing.
Step 3: Install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Step 4: Fix the Permissions Issue
By default on Linux, Docker commands require sudo. That gets annoying fast. Fix it by adding yourself to the docker group:
sudo usermod -aG docker $USER
Then log out and log back in for this to take effect. (This is the step everyone forgets. Don't be that person.)
Verify the Install
docker --version
docker run hello-world
Common Errors and How to Fix Them
Here's where most guides abandon you. Not this one. Let's go through the most common things that go wrong.
"Cannot connect to the Docker daemon"
What it looks like:
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
What it means: Docker is installed, but the Docker engine (the background service that actually does all the work) isn't running.
Fix on Windows/Mac: Open Docker Desktop. Simple as that. The daemon runs when the app is open.
Fix on Linux:
sudo systemctl start docker
# Make it start automatically on boot:
sudo systemctl enable docker
"Permission denied" on Linux
What it looks like:
permission denied while trying to connect to the Docker daemon socket
What it means: You're running Docker commands as a regular user but haven't added yourself to the docker group yet (see Step 4 above).
Fix:
sudo usermod -aG docker $USER
Then log out completely and log back in. Don't just close and reopen the terminal — actually log out of your session. If you're not sure it worked, run groups and confirm docker appears in the list.
"WSL 2 installation is incomplete" (Windows)
What it looks like: Docker Desktop shows this warning and refuses to start.
Fix: Open PowerShell as Administrator and run:
wsl --update
wsl --set-default-version 2
Then restart Docker Desktop. If that still doesn't work, go to Windows Features (search "Turn Windows features on or off"), and make sure "Virtual Machine Platform" and "Windows Subsystem for Linux" are both checked.
"Image not found" or "Unable to find image locally"
What it looks like:
Unable to find image 'something:latest' locally
This is actually not an error — it's just Docker telling you it's downloading the image. It'll finish downloading and continue. If it actually fails, check your internet connection and that you spelled the image name correctly.
"Port is already allocated"
What it looks like:
Error: bind: address already in use
What it means: You're trying to run a container on a port (like 8080) that something else on your machine is already using.
Fix: Either stop whatever's using that port, or use a different port number:
# Instead of mapping to port 8080, use 8081
docker run -p 8081:80 nginx
Running hello-world — What's Actually Happening
Okay, let's actually run something. Open your terminal and type:
docker run hello-world
Hit enter, and you'll see a wall of text. But what's actually happening under the hood? Let's walk through it step by step.
Step 1: Docker Checks Locally First
The very first thing Docker does is check whether you already have the hello-world image on your machine. An image is like a template — a frozen snapshot of a file system and some metadata. Containers are running images.
Since this is your first run, you don't have it locally, so Docker tells you:
Unable to find image 'hello-world:latest' locally
Don't panic — this is expected.
Step 2: Docker Pulls the Image from Docker Hub
Docker Hub is Docker's official registry — basically an app store for container images. Thousands of pre-built images live there: databases, web servers, language runtimes, and yes, hello-world.
Docker automatically goes to Docker Hub, finds the hello-world image, and downloads it. You'll see:
latest: Pulling from library/hello-world
Followed by some progress indicators. The image is tiny (a few kilobytes), so this happens almost instantly.
Step 3: Docker Creates and Runs a Container
With the image downloaded, Docker creates a container from it — think of it as booting up from that template. The container starts, runs the only thing it's programmed to do (print a message), and then exits.
Step 4: You See the Output
The full output looks like this:
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.
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.
Docker literally explains what just happened inside its own output. Kind of meta, but genuinely useful.
Why Does the Container Stop?
Here's something that trips up a lot of beginners: the container ran and then disappeared. If you type docker ps now, you'll see nothing.
That's because docker ps shows running containers, and hello-world has nothing more to do. It ran, printed its message, and stopped. If you want to see stopped containers:
docker ps -a
The -a flag means "all" — running and stopped. You'll see your hello-world container sitting there with a status of "Exited."
This is the key mental model: containers are not virtual machines. They don't just sit there running forever by default. They run a process, and when that process exits, the container exits. hello-world is just a program that prints some text — when the text is printed, the program is done.
A Few More Commands Worth Knowing Right Now
Since you've got Docker working, here are five commands that'll get you through your first few weeks:
# Pull an image without running it yet
docker pull ubuntu
# Run a container interactively (opens a shell inside the container)
docker run -it ubuntu bash
# List all containers (running + stopped)
docker ps -a
# Stop a running container
docker stop <container_id>
# Remove a stopped container (clean up)
docker rm <container_id>
# Remove an image you downloaded
docker rmi hello-world
The docker run -it ubuntu bash one is particularly worth trying. The -i flag means "interactive" and -t means "allocate a terminal." Together, they open a shell inside an Ubuntu container. You can explore, install packages, make changes — and when you exit, that container is gone. It's a consequence-free sandbox.
Try It Yourself — Your First Real Challenge
Now that hello-world is working, here's something to actually get your hands dirty:
Run a local web server in under 60 seconds.
docker run -p 8080:80 nginx
This downloads the official Nginx web server image and runs it, mapping port 8080 on your machine to port 80 inside the container.
Now open your browser and go to http://localhost:8080.
You should see the Nginx welcome page. You just served a web page from inside a Docker container.
Bonus challenge: Stop the container with Ctrl+C, then try running it in "detached" mode so it runs in the background:
docker run -d -p 8080:80 nginx
The -d flag means detached. Docker will print the container ID and give you your prompt back. The server is still running — check docker ps to see it. When you're done, stop it with docker stop <container_id>.
The Big Picture
Here's the thing about Docker that takes a bit to sink in: once it clicks, you stop thinking about installing software the way you used to. Instead of Googling "how to install PostgreSQL on Ubuntu" and wading through six different tutorials, you just do:
docker run postgres
Done. The right version, isolated from everything else on your machine, ready to go. And when you're done with it, you delete the container and your system is exactly as clean as before you started.
That's the promise. And once you've lived in it for a bit, going back to manual installs feels barbaric.
You've got Docker installed. You've run your first container. You've seen it work. The rest is just more of this — more containers, more images, more flags — but you've got the foundation. Go break things.
Good luck. The Docker documentation at docs.docker.com is genuinely one of the better official docs out there, worth bookmarking for when you want to go deeper.
