Introduction

Sometimes you want to quickly start a program inside a container without setting up complex files. The docker run command lets you do this by creating and starting a container from an image in one step.

When you want to test a new application image quickly without writing configuration files

When you need to run a simple web server on your local machine for development

When you want to run a database container temporarily for testing

When you want to try out a command-line tool inside a container without installing it on your computer

When you want to expose a container's service port to your local machine to access it via a browser

Commands

This command starts a new container named 'my-nginx' from the nginx image version 1.23.3. It maps port 80 inside the container to port 8080 on your computer, so you can access the web server at localhost:8080.

Terminal

docker run --name my-nginx -p 8080:80 nginx:1.23.3

Expected OutputExpected

Unable to find image 'nginx:1.23.3' locally 1.23.3: Pulling from library/nginx Digest: sha256:... Status: Downloaded newer image for nginx:1.23.3 2024/06/01 12:00:00 [notice] 1#1: using the "epoll" event method 2024/06/01 12:00:00 [notice] 1#1: nginx/1.23.3 2024/06/01 12:00:00 [notice] 1#1: built by gcc 10.2.1 20210110 (Debian 10.2.1-6) 2024/06/01 12:00:00 [notice] 1#1: OS: Linux 5.10.0-21-amd64 2024/06/01 12:00:00 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576 2024/06/01 12:00:00 [notice] 1#1: start worker processes 2024/06/01 12:00:00 [notice] 1#1: start worker process 31

→

--name - Assigns a custom name to the container for easier management

→

-p - Maps a port from the container to the host machine

This command lists all running containers so you can verify that 'my-nginx' is running and see its details.

Terminal

docker ps

Expected OutputExpected

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES abcdef123456 nginx:1.23.3 "/docker-entrypoint.…" 10 seconds ago Up 9 seconds 0.0.0.0:8080->80/tcp my-nginx

This command fetches the default web page served by the nginx container through the mapped port to confirm the server is working.

Terminal

curl http://localhost:8080

Expected OutputExpected

<!DOCTYPE html> <html> <head> <title>Welcome to nginx!</title> </head> <body> <h1>Welcome to nginx!</h1> </body> </html>

This command stops the running 'my-nginx' container when you no longer need it.

Terminal

docker stop my-nginx

Expected OutputExpected

my-nginx

This command removes the stopped container to free up system resources.

Terminal

docker rm my-nginx

Expected OutputExpected

my-nginx

Key Concept

If you remember nothing else from this pattern, remember: docker run creates and starts a container from an image in one step, optionally mapping ports and naming the container for easy access.

Common Mistakes

Not mapping container ports to host ports with -p flag

Without port mapping, services inside the container cannot be accessed from your computer

Always use -p host_port:container_port to expose container services

Using docker run without --name and then losing track of container ID

It becomes hard to manage or stop the container without a memorable name

Use --name to assign a clear name to your container

Trying to run a container from an image that does not exist locally without internet access

Docker cannot download the image and the command fails

Ensure you have internet or pre-pull the image with docker pull before running

Summary

Use docker run to start a container from an image with one command.

Map container ports to your computer ports with -p to access services.

Name your container with --name to manage it easily later.