

Sarthak Varshney is a Docker Captain, 5x C# Corner MVP, and 2x Alibaba Cloud MVP, with over six years of hands-on experience in the IT industry, specializing in cloud computing, DevOps, and modern application infrastructure. He is an Author and Associate Consultant, known for working extensively with cloud platforms and container-based technologies in real-world environments.
hello-worldOkay, 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.
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.
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.
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.
Docker Desktop Installer.exe)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.
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.
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.
.dmg fileLaunch 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.
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.
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.
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.
# 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.
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
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.)
docker --version
docker run hello-world
Here's where most guides abandon you. Not this one. Let's go through the most common things that go wrong.
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
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.
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.
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.
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
hello-world — What's Actually HappeningOkay, 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.
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.
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.
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.
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.
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.
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.
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>.
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.