Your First Docker Container Hello World

You installed Docker. Now it is time to run your very first container and understand exactly what happens at each step. This is not just about typing a command — it is about understanding the journey of that command from your keyboard to a running application.

The Command That Starts Everything

Open your terminal and type:

docker run hello-world

That single command does five things automatically. Most beginners type it and move on without realizing how much work happened. Let us break it down.

What Happens When You Run That Command

You type: docker run hello-world

┌──────────────────────────────────────────────────────┐
│  Step 1: Docker CLI sends request to Docker Daemon   │
│          "Please run an image called hello-world"    │
└──────────────────────────┬───────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────┐
│  Step 2: Daemon checks local image cache             │
│          "Do I have hello-world stored locally?"     │
│          → NO → go to Docker Hub                     │
└──────────────────────────┬───────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────┐
│  Step 3: Pull image from Docker Hub                  │
│          Downloads hello-world image (~13 KB)        │
│          Stores it in local cache for next time      │
└──────────────────────────┬───────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────┐
│  Step 4: Create a container from the image           │
│          Adds writable layer, sets up namespace      │
└──────────────────────────┬───────────────────────────┘
                           ↓
┌──────────────────────────────────────────────────────┐
│  Step 5: Run the container's default command         │
│          Prints the Hello World message              │
│          Container exits (job complete)              │
└──────────────────────────────────────────────────────┘

Understanding the Output

The output message from Docker is actually a self-description of exactly what it did. It explains the four steps it took to produce that message. Reading it carefully teaches you the Docker pull → create → run cycle.

Running a More Useful Container — nginx Web Server

The hello-world container runs and exits. Real containers keep running. Let us start a web server:

docker run -d -p 8080:80 nginx

Break down each part of this command:

  • docker run — Start a new container
  • -d — Detached mode: runs in the background, does not block your terminal
  • -p 8080:80 — Port mapping: forward traffic from port 8080 on your machine to port 80 inside the container
  • nginx — The image name to use
Port Mapping Diagram:

Your Machine                  Container
┌──────────────┐              ┌──────────────┐
│              │              │              │
│  Port 8080   │──────────────│  Port 80     │
│              │              │  nginx here  │
└──────────────┘              └──────────────┘

You visit: http://localhost:8080
nginx receives it on: port 80 inside the container

Open your browser and go to http://localhost:8080. You see the nginx welcome page. A web server is running inside a Docker container on your machine.

Useful Commands for Your First Container

Check which containers are currently running:

docker ps

You see a table showing the container ID, image name, when it started, and the port mapping.

Stop the container (replace abc123 with your actual container ID from docker ps):

docker stop abc123

See all containers including stopped ones:

docker ps -a

Run a container with a custom name so you do not need to track random IDs:

docker run -d -p 8080:80 --name my-webserver nginx
docker stop my-webserver
docker start my-webserver

Running a Container and Getting Inside It

You can open an interactive terminal inside a running container, like logging into a tiny computer:

docker run -it ubuntu bash

The -it flag means interactive terminal. bash is the command to run inside the container. You land inside a Ubuntu container. Type ls, pwd, echo hello — these run inside the container. Type exit to leave.

Key Points

  • docker run pulls the image if needed, creates a container, and starts it.
  • -d runs in the background; -p host:container maps ports.
  • docker ps lists running containers; docker ps -a lists all containers.
  • Use --name to give containers memorable names instead of random IDs.
Previous lessons
Back to courses
Next lessons

Leave a Comment