Your First Container

You have Docker installed and the hello-world test passed. Now it is time to run real containers: a Linux shell you can type into and a web server you can open in your browser. Along the way you will see exactly what Docker does when you type docker run.

By the end of this lesson you will be able to start, list, stop and remove containers, which is most of what you do with Docker every day.

What happens when you type docker run

The docker command you type is only a client. It sends your request to the Docker daemon (dockerd), the background service that does the real work. When you run docker run hello-world, the daemon does four things:

1. Looks for the image hello-world:latest on your computer.
2. Pulls it from Docker Hub if it is not there.
3. Creates a new container from the image: a writable layer on top of the image, its own network settings and a name.
4. Starts the container, which runs the image's default command. When that command ends, the container stops.

The container does not disappear when it stops. It stays on disk in the Exited state until you remove it. That surprises many beginners, and you will see why it matters below.

An interactive shell inside a container

Let's start a container from the official Ubuntu image and work inside it. Two options make it interactive: -i keeps the input open so you can type, and -t gives you a proper terminal. They are almost always written together as -it.

docker run -it ubuntu:26.04 bash

Unable to find image 'ubuntu:26.04' locally
26.04: Pulling from library/ubuntu
9c3f8b2e4d71: Pull complete
Digest: sha256:4f6c5a0b6c1e8d2a9e7b3f0c5d1a8e6b2c9f4a7d3e0b1c8f5a2d6e9b3c7f0a14
Status: Downloaded newer image for ubuntu:26.04
root@e5b2a9f31c06:/#

The prompt changed. You are now root inside a container whose host name is its short container ID, e5b2a9f31c06. Try a few commands:

cat /etc/os-release | head -n 2
ls /home
apt update && apt install -y curl
exit

You are root inside the container, so you can install packages freely. Nothing you do here touches your own computer. When you type exit, the shell (the container's main process) ends, so the container stops.

Here is the important part: if you run docker run -it ubuntu:26.04 bash again, you get a brand-new container, and curl is not installed in it. Each docker run creates a fresh container from the unchanged image. Changes made inside a container stay in that one container only. To make changes permanent, you write them in a Dockerfile, which you will do in Writing a Dockerfile.

A web server in the background

Most containers run services that should keep going after you close the terminal. The -d option (detached) starts the container in the background and prints its full ID. The -p 8080:80 option publishes a port: requests to port 8080 on your computer go to port 80 inside the container. The --name option gives the container a name you can remember.

docker run -d -p 8080:80 --name chai-site nginx:alpine

8c41d07e2b95f0b3a6d2c4e1f7a9b8c0d3e5f2a1b4c6d8e0f9a7b3c5d1e2f4a6

Open http://localhost:8080. The Nginx welcome page means the server inside the container is answering. The lesson docker run: Ports, Names, Detached & Env explains -p, -d, --name and other options in detail.

Listing containers

docker ps lists running containers. Add -a (all) to include stopped ones:

docker ps -a

CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS                      PORTS                                     NAMES
8c41d07e2b95   nginx:alpine   "/docker-entrypoint.…"   2 minutes ago    Up 2 minutes                0.0.0.0:8080->80/tcp, [::]:8080->80/tcp   chai-site
e5b2a9f31c06   ubuntu:26.04   "bash"                   6 minutes ago    Exited (0) 4 minutes ago                                              cranky_kapitsa
b7d3e0a4f812   hello-world    "/hello"                 15 minutes ago   Exited (0) 15 minutes ago                                             festive_raman

Each column tells you something useful:

• CONTAINER ID: the first 12 characters of the full ID. You can use any unique start of it, such as e5b, in commands.
• COMMAND: the program the container runs. Long commands are cut short with ….
• STATUS: Up means running. Exited (0) means the main program finished with exit code 0, which is success. Any other number means it failed.
• PORTS: published ports. 0.0.0.0 is every IPv4 address of your computer and [::] is every IPv6 address.
• NAMES: your --name, or a random name such as festive_raman that Docker makes up from an adjective and the surname of a famous scientist.

Stopping, starting and removing

docker stop chai-site      # ask the main process to shut down
docker start chai-site     # start the same container again
docker rm cranky_kapitsa   # remove a stopped container
docker rm -f chai-site     # stop and remove in one step

docker stop sends the SIGTERM signal so the program can finish cleanly. If it is still running after 10 seconds, Docker sends SIGKILL to force it. docker start restarts an existing container with all its earlier settings; it does not create a new one.

Stopped containers pile up quickly while you experiment. The --rm option removes a container automatically when it stops, which is perfect for one-off commands:

docker run --rm -it ubuntu:26.04 bash
docker container prune

The second command removes all stopped containers after asking you to confirm.

Getting help

Every command has built-in help. docker --help lists all commands, and docker run --help lists every option for run. The help is long, so search it:

docker run --help | grep -i restart

--restart string                   Restart policy to apply when a container exits (default "no")

Common mistakes

• Expecting changes inside a container to survive docker run. Each docker run starts from the clean image. Use docker start to reuse a stopped container, a volume to keep data, or a Dockerfile to change the image.
• Leaving dozens of stopped containers behind. Use --rm for throwaway runs and docker container prune now and then.
• "Conflict. The container name /chai-site is already in use". A container with that name exists, even if it is stopped. Remove it with docker rm chai-site or choose a new name.
• Forgetting -it for a shell. Without it, docker run ubuntu:26.04 bash starts bash with no input, so it exits at once.

Key points

• docker run finds or pulls the image, creates a container and starts its main command.
• -it gives you an interactive terminal; -d runs the container in the background.
• A container stops when its main process ends and stays in the Exited state until removed.
• docker ps -a lists all containers; the STATUS column shows Up or Exited (code).
• docker stop, docker start, docker rm and docker rm -f manage a container's life; --rm cleans up automatically.

docker run -d -p 9090:80 --name rohtak-news nginx:alpine
docker ps
docker run --rm -it alpine:3.22 sh
date
exit
docker rm -f rohtak-news