Lesson 3 of 8 in Containers with Docker

Running and inspecting containers

Core10 min

docker run creates a container from an image and starts it. The container lives only while its main process runs, and you inspect it with commands such as docker ps, docker logs and docker exec.

Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.

Read these first: Images, layers and tags

The problem this solves

Once you have an image, you need to start it, reach it from your browser, give it settings, and find out what it is doing. A container has its own network and its own filesystem, so none of that happens automatically.

Beginners often get stuck because a container looks like a small computer, but it behaves like a single program. When that program stops, the container stops, and the only trace is the logs.

How it works

The life of a container
The life of a containerAn image is started as a running container, stopping it leaves an exited container with its logs, and removing it deletes it.1 docker run2 dockerstop3 docker rmImagenginx:alpineRunningmain process aliveExitedprocess endedRemovedlayer deleted
  • Data
  • Runs code
  • Other

An image is started as a running container, stopping it leaves an exited container with its logs, and removing it deletes it.

  1. Image to Running: 1 docker run
  2. Running to Exited: 2 docker stop
  3. Exited to Removed: 3 docker rm
Reaching a container through a published port
Reaching a container through a published portYour browser sends a request to a port on your computer, Docker forwards it to the container's port, and the program's output is kept as logs.1 request2 forwardedto :803 stdout and stderrBrowserlocalhost:8080Host port 8080opened by Dockerweb containerlistens on port 80Logsread by docker logs
  • People and clients
  • Network
  • Runs code
  • Data

Your browser sends a request to a port on your computer, Docker forwards it to the container's port, and the program's output is kept as logs.

  1. Browser to Host port 8080: 1 request
  2. Host port 8080 to web container: 2 forwarded to :80
  3. web container to Logs: 3 stdout and stderr

A container has one main process, the command from the image's CMD or ENTRYPOINT. While it runs, the container is running. When it exits, the container is exited, but it still exists with its logs and writable layer until you remove it.

-p 8080:80 publishes a port. It means: listen on port 8080 of the host, and forward connections to port 80 inside the container. The left number is the host, the right number is the container.

Programs in containers write to standard output and standard error, and Docker keeps that as the container's logs. docker exec starts an extra process inside a running container, which is how you open a shell to look around.

Try it yourself

Run these in a Linux, macOS or WSL shell. Everything is removed at the end.

  1. 1
    Start a web server in the background
    docker run -d --name web -p 8080:80 nginx:alpine

    -d detaches, --name gives it a name you can use instead of an ID, -p publishes the port.

  2. 2
    Talk to it and read its logs
    curl http://localhost:8080
    docker logs web

    The curl shows the nginx welcome page. The logs show your request. Add -f to docker logs to follow new lines.

  3. 3
    List containers, then look inside
    docker ps
    docker exec -it web sh

    docker ps shows running containers. Inside the shell try ls /usr/share/nginx/html, then type exit.

  4. 4
    Pass a setting as an environment variable
    docker run --rm -e GREETING=hello alpine sh -c 'echo $GREETING'

    You should see

    hello

    The single quotes make the container's shell expand $GREETING, not your host shell.

  5. 5
    Stop, see it exited, remove it
    docker stop web
    docker ps -a
    docker rm web

    After stop, docker ps no longer lists it but docker ps -a does, with an Exited status.

What breaks, and where to look

  • docker: Error response from daemon: ... Bind for 0.0.0.0:8080 failed: port is already allocated.

    WHY IT HAPPENS
    Something already uses port 8080 on the host: another container, or a local program. Docker Desktop may word it as address already in use.
    CHECK FIRST
    Run docker ps to find a container publishing it. On Linux or macOS run lsof -i :8080 or ss -ltnp to find the other program, then free it or choose another host port such as -p 8081:80.
  • docker: Error response from daemon: Conflict. The container name "/web" is already in use by container "<container-id>".

    WHY IT HAPPENS
    A stopped container called web still exists. Container names must be unique, and exited containers keep their name.
    CHECK FIRST
    Run docker ps -a to see it, then docker rm web. Using --rm in docker run avoids leftovers for throwaway containers.
  • You run a container and it ends straight away. docker ps shows nothing, docker ps -a shows Exited.

    WHY IT HAPPENS
    The main process finished or crashed. Containers do not stay alive on their own, so a script that ends, or a program that fails at startup, ends the container.
    CHECK FIRST
    Run docker logs <name> for the last output and error, and read the exit code in docker ps -a.

When not to use this

  • Do not use docker exec to fix a running container by hand. Changes made that way vanish on the next start. Fix the image or the config instead.
  • Publishing a port with -p exposes it on all host network interfaces by default. For something private, publish to loopback only, for example -p 127.0.0.1:8080:80.

Check yourself

In -p 8080:80, which number is the container's port?

80. The left number is the host port and the right number is the container port.

Why can a container stop within a second of starting?

A container lives only as long as its main process. If that process exits or crashes, the container exits.

Where do you look first when a container misbehaves?

docker logs <name>, then docker ps -a for its status and exit code.

Lesson 41 of 92 in the DevOps path

Search

Search cheat sheets and projects