Saltar a contenido

01 - Setup

What this session is

About 30 minutes. Install Docker (or Podman), confirm it works, run your first container.

Step 1: Install

macOS / Windows: Docker Desktop Download from docker.com/products/docker-desktop. Run the installer. Open the Docker Desktop app once - it sets up the engine in the background. Free for personal / small-business use.

Linux: Docker Engine (Debian/Ubuntu example) 

sudo apt install docker.io docker-compose-v2
sudo usermod -aG docker $USER
Log out and back in for the group change. Now you can run docker without sudo.

Linux alternative: Podman 

sudo apt install podman podman-compose
No root daemon. Optionally alias docker=podman to make commands portable.

Step 2: Verify

docker --version
docker info

Both should print something. docker info reports the engine version, OS, storage driver, etc.

If docker: command not found - install didn't complete. If Cannot connect to the Docker daemon - Docker Desktop isn't running (macOS/Windows), or the systemd service is off (Linux: sudo systemctl start docker).

Step 3: Run your first container

docker run hello-world

What happens: 1. Docker looks for an image named hello-world locally. Doesn't find it. 2. Pulls it from Docker Hub. 3. Creates a container from it. 4. Runs the container's default command (which prints a friendly message). 5. The container exits when the command finishes.

You should see:

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
...
Hello from Docker!
This message shows that your installation appears to be working correctly.

Congratulations - your first container.

Step 4: A more useful container

Let's run a real Linux distribution interactively:

docker run -it --rm ubuntu bash

You're now inside a fresh Ubuntu container. Try:

cat /etc/os-release
ls /
whoami
ps aux
exit

exit terminates the shell, which terminates the container. Because of --rm, the container is also automatically removed.

What's new:

  • -i (--interactive) - keep stdin open. Lets you type at the container.
  • -t (--tty) - allocate a pseudo-terminal. Makes the shell behave like a real terminal.
  • --rm - clean up the container after it exits. Without this, stopped containers accumulate.
  • ubuntu - the image.
  • bash - the command to run inside the container.

-it together is the standard "I want an interactive shell" combo.

Step 5: A container with a port

Let's run a web server:

docker run -d --rm -p 8080:80 --name webtest nginx

What's new:

  • -d (--detach) - run in the background (returns to your terminal immediately).
  • -p 8080:80 - map host port 8080 to container port 80.
  • --name webtest - give the container a name (so you can refer to it).

Open http://localhost:8080 in your browser. You should see the nginx welcome page. The container is serving HTTP on port 80; Docker forwarded it to your host's port 8080.

To stop it:

docker stop webtest

Since we used --rm, the container is also removed when it stops.

Common docker run flags (preview - full list in page 02)

Flag What it does
-it Interactive shell
--rm Remove container when it exits
-d Detached / background
-p HOST:CONTAINER Port mapping
-v HOST:CONTAINER Volume / bind mount
-e VAR=value Environment variable
--name NAME Name the container
--network NAME Connect to a specific network

You'll meet each in detail.

Try changing things

  1. Run docker run --rm alpine echo "hi from alpine". Notice Alpine is tiny (~5MB).
  2. Run docker run --rm python:3 python -c "print(1+1)". The container has Python; you used it once and threw it away.
  3. Run docker run -it --rm node:20 node - get a Node.js REPL.
  4. Run docker ps (lists running containers - probably empty if you used --rm).
  5. Run docker ps -a (lists all containers including stopped - also probably empty with --rm).

What just happened, conceptually

You can run any program from any (compatible) Linux distribution without installing it. Need Python 3? docker run python:3. Need a Postgres database? docker run postgres. Need to test on Debian instead of your usual Ubuntu? docker run -it debian bash.

The container is isolated - its filesystem and processes don't touch yours. Quit it and nothing leaks. The "throwaway environment" use case is huge.

What you might wonder

"Where did nginx and ubuntu come from?" Docker Hub. The default registry. docker pull ubuntu is shorthand for docker pull docker.io/library/ubuntu:latest. We'll cover registries in page 11.

"What's a 'tag'?" A version identifier on an image. ubuntu:24.04 and ubuntu:22.04 are different versions. ubuntu alone defaults to ubuntu:latest. Page 03.

"Did Docker install Ubuntu on my machine?" No. Your host OS is unchanged. The container has its own copy of Ubuntu's userspace, but uses your host's kernel. When the container exits, that filesystem can be removed.

"Is this safe? Could a container break my host?" By default, containers are fairly isolated but not fully secure. Don't run untrusted images, don't --privileged, don't mount sensitive host paths. We'll cover security basics in page 10.

"Why docker run --rm?" Without --rm, stopped containers stick around. Useful for debugging stopped containers but accumulates clutter. For one-shot commands, --rm is the right default.

Done

  • Docker installed and working.
  • Pulled and ran a "hello world" container.
  • Ran a Linux distribution interactively (-it).
  • Ran a web server with port mapping (-p).
  • Recognized the common docker run flags.

Next: Running containers →

Comments