Docker Essentials

Docker is the backbone of the Beginner tier and most of Intermediate - worth understanding properly rather than just copy-pasting docker run commands.

Why Docker fits a homelab

Installing services directly on your OS (apt install jellyfin, apt install pihole, and so on) works, but every service ends up sharing the same set of system libraries, competing for the same config file locations, and leaving traces behind when you remove them. Docker packages each service with everything it needs, isolated from the others, so you can:

• Run conflicting versions of things side by side.
• Delete a service completely by removing its container and volume - no leftover files scattered across the filesystem.
• Move your whole setup to a new machine by copying a handful of compose files and volumes.
• Try something and throw it away in minutes if it's not for you.

Image vs. container vs. volume

Three terms that get used loosely but mean specific things:

• Image - a read-only template: the application plus everything it needs to run, packaged together. You don't run an image directly, you run a container from it.
• Container - a running (or stopped) instance of an image. You can run multiple containers from the same image, each isolated from the others.
• Volume - persistent storage that lives outside the container's own filesystem. This matters because a container's own filesystem is disposable - if you delete the container, anything not in a volume is gone with it.

The practical rule: any data you care about must be in a volume, never left in the container's own writable layer.

Install Docker

Use Docker's official install script rather than your distro's package manager - it stays more current with Docker's own releases:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect, then confirm:

docker run hello-world

⚠️ Risk: adding your user to the docker group is effectively equivalent to giving that user root access to the host - anyone who can run Docker containers can mount the host filesystem into one. Fine for your own admin account on a homelab; don't do it for accounts you don't fully trust.

Running your first container

docker run -d \
  --name whoami \
  -p 8080:80 \
  --restart unless-stopped \
  traefik/whoami

• -d - run detached (in the background)
• --name - a human-readable name instead of a random one
• -p 8080:80 - map port 8080 on the host to port 80 in the container
• --restart unless-stopped - start automatically on boot/crash, but respect a manual docker stop

Visit http://server-ip:8080 and you'll see the container respond. Tear it down when you're done exploring:

docker stop whoami && docker rm whoami

Useful everyday commands

docker ps                 # running containers
docker ps -a               # all containers, including stopped
docker images               # images downloaded locally
docker logs -f whoami        # follow a container's logs
docker exec -it whoami sh     # open a shell inside a running container
docker stats                   # live CPU/RAM usage per container

Running individual docker run commands for every service gets unwieldy fast once you have more than two or three - see Docker Compose Basics for the fix.