Docker Fundamentals: Run Your First Container

An image becomes a container the moment you run it.

The command below does four things at once. -d runs the container detached so nginx keeps serving in the background instead of tying up your terminal. --name web gives the container a human-friendly handle you will use in every later command (otherwise Docker invents a random name like grumpy_beaver). -p 8080:80 publishes the container's internal port 80 to host port 8080, without it, nginx would be reachable only from inside Docker's private network. Finally, nginx:stable is the image reference: the stable tag tracks nginx's stable release line, which moves less often than latest but still floats with each release. For true repeatability you would pin the digest (nginx:stable@sha256:...), an immutable build identifier, as step 08 explains.

The first run prints pull progress as each image layer downloads, then a long hex string, the full container ID, once the container is up.

Expected output:

$ docker run -d --name web -p 8080:80 nginx:stable
8f2c1a4b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3

What this teaches: Running a container is starting an isolated process from an image; flags control its network, storage, and lifetime.

docker ps is your dashboard: it shows every running container with its image, status, published ports, and name. Add -a to also see stopped containers, this is the single most useful flag when debugging, because a container that crashed two seconds after launch is invisible to a plain docker ps.

For the full picture, docker inspect dumps the container's complete configuration as JSON: mounts, environment variables, network settings, restart policy, and more. Piping it through a Go template with --format (or through jq) lets you pull out exactly one field, which is how you will script against Docker later.

PULL ONE FIELD OUT OF INSPECT

docker inspect --format '{{.State.Status}} | {{.Config.Image}} | {{.HostConfig.RestartPolicy.Name}}' web

Expected output:

$ docker ps --format '{{.Names}} {{.Status}}'
web Up 10 seconds

What this teaches: Listing and inspecting shows the difference between what you asked for and what Docker actually created.

Volumes keep data when a container is removed, the key to stateful workloads.

Anything a container writes to its own filesystem lives in a writable layer that is destroyed with the container. A named volume is the escape hatch: Docker stores it under /var/lib/docker/volumes/ on the host and mounts it into the container at a path you choose. Here we mount a volume called webdata over nginx's document root, /usr/share/nginx/html, so the site's files survive no matter what happens to the container serving them.

Now prove persistence. Write a custom page into the volume through web2, confirm it is served, then delete the container entirely and attach the same volume to a brand-new container, web3. If the page is still there, the data lived in the volume, not in the container.

WRITE, DESTROY, REATTACH

docker exec web2 sh -c 'echo "<h1>persisted by webdata</h1>" > /usr/share/nginx/html/index.html'
curl -s http://localhost:8081        # shows our custom page

docker rm -f web2                    # container is gone
docker run -d --name web3 -p 8081:80 -v webdata:/usr/share/nginx/html nginx:stable
curl -s http://localhost:8081        # still shows our custom page

Expected output:

$ docker volume create webdata && docker run -d --name web2 -p 8081:80 -v webdata:/usr/share/nginx/html nginx:stable
webdata
9e8d7c6b5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8

What this teaches: Volumes persist data outside the container's writable layer; without one, data dies with the container.

Docker captures whatever a container writes to stdout and stderr and stores it per container, so well-behaved images like nginx never need log files on disk. docker logs is how you read that stream. --tail 10 shows the last ten lines, -f follows new output live (like tail -f), and --timestamps prefixes each line with an RFC 3339 timestamp, which is invaluable when correlating events across containers.

Hit the server once with curl, then read the log: you should see your own request recorded with your client IP (from Docker's bridge network), the path, and the 200 status. This request-then-log loop is the most basic debugging rhythm in container work.

Expected output:

/docker-entrypoint.sh: Configuration complete; ready for start up

What this teaches: Logs are the container's stdout and stderr; reading them is the first debugging step for any misbehaving app.

Sometimes reading logs is not enough and you need to look around inside. docker exec starts an additional process inside an already-running container; combined with -it (interactive TTY) and a shell, it drops you into a live session. This is the container equivalent of SSH, without any SSH server installed.

OPEN A SHELL IN THE CONTAINER

docker exec -it web sh
# inside the container:
ls /usr/share/nginx/html
cat /etc/nginx/conf.d/default.conf
exit

Expected output:

$ docker exec hello hostname
8f2c1a4b5d6e

Use this to check config files, test DNS resolution, or verify which process is PID 1. Remember that any changes you make from inside are ephemeral unless they land on a mounted volume, the whole point of step 03.

What this teaches: Exec runs a new process inside the container's namespaces; it is for inspection, not for configuration.

A container is a process with an on/off switch, not a machine you reinstall. docker stop sends SIGTERM and waits (ten seconds by default) before SIGKILL; docker start resurrects a stopped container with all its filesystem changes and port mappings intact; docker rm deletes the stopped container and its writable layer for good. Knowing the difference saves you from rebuilding containers you could have simply restarted.

FULL LIFECYCLE IN FOUR COMMANDS

docker stop web            # graceful shutdown; curl now fails
docker ps -a               # web shows "Exited (0)"
docker start web           # same container back up, port 8080 works again
docker rm -f web           # force-remove even while running

Expected output:

$ docker stop hello && docker rm hello
hello
hello

Note the exit code: Exited (0) means the process shut down cleanly. A nonzero code like Exited (1) or Exited (137) (SIGKILL, often the OOM killer) is your first clue when a container will not stay up. Finish by force-removing the container so later labs start from a clean slate; -f combines stop and remove in one step.

What this teaches: Stop, start, and remove are the lifecycle verbs; removing is what reclaims the writable layer.

Every container gets its own network namespace and an IP address on one of Docker's virtual networks. Out of the box, containers attach to the default bridge network (subnet 172.17.0.0/16) and can reach the internet outbound, but inbound traffic only arrives through ports you explicitly publish with -p. Understanding this split, internal reachability versus published ports, is what makes container networking click.

LOOK UNDER THE HOOD

docker network ls
docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web3
docker network inspect bridge --format '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'

Expected output:

$ docker port hello
80/tcp -> 0.0.0.0:8080

Try it: curl http://172.17.0.2 from the host reaches nginx on the container's internal IP without any published port, because the host sits on the bridge too. Other machines on your LAN cannot do this, from the outside, only published ports exist. That default-deny posture is a genuine security feature of the bridge model.

What this teaches: Container networking defaults to a bridge with NAT; -p is the controlled hole you punch in it.

Containers are disposable; images are what accumulate. Every docker run against a new tag downloads more layers to your disk, so knowing how to list, inspect, and remove images keeps a lab VM healthy. An image reference has three parts: the registry (defaulting to Docker Hub), the repository (library/nginx for official images), and the tag (stable). Tags are mutable labels, latest today may not be latest tomorrow, while the digest (sha256:...) pins an exact, immutable build.

LIST AND INSPECT LOCAL IMAGES

docker images
docker history nginx:stable          # one line per layer
docker image inspect nginx:stable --format '{{.RepoTags}} {{.Size}}'

Expected output:

$ docker images --format '{{.Repository}}:{{.Tag}} {{.Size}}'
nginx:1.27 188MB

docker history is worth a look: images are stacks of read-only layers, and layers shared between images (two nginx tags, for example) are stored only once. This is why pulling a second tag of the same image is usually fast, Docker downloads just the layers it does not already have.

REMOVE WHAT YOU NO LONGER NEED

docker rmi hello-world             # remove by name:tag
docker image prune                 # drop dangling (untagged) layers only

What this teaches: Tags are mutable aliases and layers are the cost; pruning reclaims what you no longer need.