Run your first container and learn the core commands

Originally published on docker.learnio.dev — part of the Docker fundamentals course. View this lesson on the original site.

Run one useful container

The fastest way to make Docker concrete is a tiny web server you can curl from your machine.

See it

{
  "ariaLabel": "docker run nginx with port publish and detach",
  "segments": [
    { "text": "docker", "bottomLabel": { "text": "CLI" } },
    { "text": "run", "topLabel": { "text": "Command", "variant": "command" }, "highlight": "command" },
    { "text": "--rm -d", "bottomLabel": { "text": "Detached, auto-remove" } },
    { "text": "-p", "bottomLabel": { "text": "Publish port" } },
    { "text": "127.0.0.1:8080:80", "wide": true },
    { "text": "nginx:stable-alpine", "topLabel": { "text": "Image tag", "variant": "tag" }, "highlight": "tag" }
  ]
}

Try it

docker run --rm -d --name hello-nginx -p 127.0.0.1:8080:80 nginx:stable-alpine
curl -I http://127.0.0.1:8080
docker ps --filter name=hello-nginx
docker logs hello-nginx
docker stop hello-nginx

You should see HTTP/1.1 200 from curl and the container listed in docker ps.

If it goes wrong

Port 8080 already in use

docker run may report that the port is already allocated. Free the name, then publish nginx on another host port:

docker rm -f hello-nginx 2>/dev/null || true
docker run --rm -d --name hello-nginx -p 127.0.0.1:8081:80 nginx:stable-alpine
curl -I http://127.0.0.1:8081

To see what is bound to 8080: docker ps --format '{{.Names}} {{.Ports}}' | grep 8080 or lsof -i :8080 on macOS/Linux.

Name hello-nginx already in use

A stopped container can still hold the name until you remove it:

docker rm -f hello-nginx
docker run --rm -d --name hello-nginx -p 127.0.0.1:8080:80 nginx:stable-alpine

Pull errors

Retry the image pull and confirm Docker can reach the registry:

docker pull nginx:stable-alpine

If Docker Hub rate-limits you, run docker login. On Apple Silicon, while debugging a platform mismatch only, try:

docker pull --platform linux/amd64 nginx:stable-alpine

Connection refused or missing from docker ps

The container may have exited right after start. Inspect, read logs, remove the old instance, and run again:

docker ps -a --filter name=hello-nginx
docker logs hello-nginx
docker rm -f hello-nginx
docker run --rm -d --name hello-nginx -p 127.0.0.1:8080:80 nginx:stable-alpine
docker ps --filter name=hello-nginx
curl -I http://127.0.0.1:8080

You want STATUS containing Up and HTTP/1.1 200 (or similar) from curl.

Remember

If this nginx smoke test works, later PHP failures are more likely app config than “Docker is broken.”

From Docker fundamentals — Install Docker, see the value, and learn the basics