Start a container with `docker run`

docker run is the most frequently used Docker command—it creates and starts a container. Mastering its parameters means mastering the essentials of running containers.

1. What You'll Learn

• Key parameters of docker run
• Front-end vs. Back-end Operation Modes
• Port mapping mechanism
• Container Naming and Automatic Cleanup
• Resource limitations (CPU/memory)

2. A True Story of a Backend Developer

(1) Pain Point: Conflicts Between Multiple Database Versions

Alice needs to run three versions of PostgreSQL—v15, v14, and v13—simultaneously on her local machine to test compatibility. With the traditional installation method, she can only install one version at a time, and switching versions requires uninstalling and reinstalling, which takes 30 minutes each time. To make matters worse, the configuration files and data directories of different versions may conflict with one another.

(2) Solutions for Parallel Execution of Multiple Docker Containers

Using Docker, I started three PostgreSQL instances with a single command, each mapped to a different port.

# Run three PostgreSQL versions side by side
docker run -d --name pg15 -e POSTGRES_PASSWORD=secret -p 5432:5432 postgres:15
docker run -d --name pg14 -e POSTGRES_PASSWORD=secret -p 5433:5432 postgres:14
docker run -d --name pg13 -e POSTGRES_PASSWORD=secret -p 5434:5432 postgres:13

(3) Benefits: Multiple versions running in parallel with zero conflicts

With three PostgreSQL instances running in parallel without interfering with one another, Alice completed the cross-version compatibility testing in 5 minutes—a task that would have taken 2 hours using the traditional method.

3. docker run Syntax and Key Parameters

(1) Basic Syntax

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

(2) Quick Reference Table for Common Parameters

4. Front-End vs. Back-End Execution

Containers have two running modes: foreground and detached, which are controlled by -it and -d.

(1) Comparison of Operating Modes

▶ Example: Starting the Nginx service in the background (Difficulty: ⭐)

# Run Nginx in detached mode
docker run -d -p 8080:80 --name web nginx:latest

# View logs from the background container
docker logs web

a1b2c3d4e5f6... (container ID)
/docker-entrypoint.sh: Launching nginx...

▶ Example: Launching an Interactive Ubuntu Container (Difficulty: ⭐⭐)

# Run Ubuntu with interactive terminal
docker run -it ubuntu:22.04 bash

# Inside the container: check OS info
cat /etc/os-release

# Exit the container
exit

root@a1b2c3d4e5f6:/# cat /etc/os-release
NAME="Ubuntu"
VERSION="22.04.3 LTS (Jammy Jellyfish)"
...
root@a1b2c3d4e5f6:/# exit

5. Port Mapping

By default, service ports inside a container are not accessible from the outside; port mapping exposes the container's ports to the host.

graph LR
    A["Host<br/>Port 8080"] -->|"-p 8080:80"| B["Container<br/>Port 80"]
    C["Host<br/>Port 5432"] -->|"-p 5432:5432"| D["Container<br/>Port 5432"]

graph LR
    A["Host<br/>Port 8080"] -->|"-p 8080:80"| B["Container<br/>Port 80"]
    C["Host<br/>Port 5432"] -->|"-p 5432:5432"| D["Container<br/>Port 5432"]

(1) Port Mapping Policy

▶ Example: Multi-Port Mapping for PostgreSQL (Difficulty: ⭐⭐)

# Run PostgreSQL with port mapping and environment variables
docker run -d \
  --name pg15 \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=myapp \
  -p 5432:5432 \
  postgres:15

# Connect to PostgreSQL
docker exec -it pg15 psql -U postgres -d myapp

myapp=# \l
                                  List of databases
   Name    |  Owner   | Encoding |  Collate   |   Ctype    
-----------+----------+----------+------------+------------
 myapp     | postgres | UTF8     | en_US.utf8 | en_US.utf8
 postgres  | postgres | UTF8     | en_US.utf8 | en_US.utf8

6. Automatic Cleanup and Restart Policies

(1) --rm Temporary Container

--rm Automatically delete the container after it exits; suitable for one-time tasks.

▶ Example: Running a temporary task with --rm (Difficulty: ⭐)

# Run a one-off command, container auto-removes after exit
docker run --rm alpine:latest echo "Hello from Alpine!"

# Verify: container is gone
docker ps -a

Hello from Alpine!

(2) Restart Policy

The restart policy determines whether a container is automatically restarted after it exits.

▶ Example: Configuring Automatic Restart (Difficulty: ⭐⭐)

# Run Nginx with restart policy
docker run -d --name web --restart=always -p 8080:80 nginx:latest

# Simulate crash: kill the container process
docker kill web

# Wait a few seconds, check: it restarted automatically
docker ps

CONTAINER ID   IMAGE          STATUS                     PORTS                  NAMES
b2c3d4e5f6a7   nginx:latest   Up 3 seconds (healthy)     0.0.0.0:8080->80/tcp   web

7. Resource Limitations

Docker can limit the amount of CPU and memory used by containers, preventing a single container from exhausting the host's resources.

(1) Resource Limit Parameters

▶ Example: Limit container memory to 256MB (Difficulty: ⭐⭐)

# Run a container with 256 MB memory limit
docker run -d --name limited-app --memory=256m nginx:latest

# Verify the memory limit
docker inspect limited-app --format='{{.HostConfig.Memory}}'

268435456

8. Container Lifecycle and State Transitions

stateDiagram-v2
    [*] --> Created : docker create / docker run
    Created --> Running : docker start / docker run
    Running --> Paused : docker pause
    Paused --> Running : docker unpause
    Running --> Stopped : docker stop / docker kill
    Stopped --> Running : docker start
    Running --> Restarting : crash + restart policy
    Restarting --> Running : restart succeeds
    Stopped --> Deleted : docker rm
    Running --> Deleted : docker rm -f
    Deleted --> [*]

stateDiagram-v2
    [*] --> Created : docker create / docker run
    Created --> Running : docker start / docker run
    Running --> Paused : docker pause
    Paused --> Running : docker unpause
    Running --> Stopped : docker stop / docker kill
    Stopped --> Running : docker start
    Running --> Restarting : crash + restart policy
    Restarting --> Running : restart succeeds
    Stopped --> Deleted : docker rm
    Running --> Deleted : docker rm -f
    Deleted --> [*]

9. Complete Example: Starting a PostgreSQL Container with Environment Variables

# ============================================
# Complete walkthrough: Run PostgreSQL with Docker
# Covers: -d, -e, -p, --name, --restart, --memory
# ============================================

# 1. Run PostgreSQL 15 with full configuration
docker run -d \
  --name pg15 \
  -e POSTGRES_USER=appuser \
  -e POSTGRES_PASSWORD=secret123 \
  -e POSTGRES_DB=appdb \
  -p 5432:5432 \
  --restart=unless-stopped \
  --memory=512m \
  postgres:15

# 2. Verify the container is running
docker ps

# 3. Connect via psql client inside the container
docker exec -it pg15 psql -U appuser -d appdb

# 4. Inside psql: create a test table
# CREATE TABLE users (id SERIAL PRIMARY KEY, name VARCHAR(100));
# INSERT INTO users (name) VALUES ('Alice'), ('Bob');
# SELECT * FROM users;

# 5. Check container resource usage
docker stats pg15 --no-stream

# 6. View container configuration
docker inspect pg15 --format='Memory: {{.HostConfig.Memory}}, RestartPolicy: {{.HostConfig.RestartPolicy.Name}}'

# docker ps
CONTAINER ID   IMAGE         STATUS         PORTS                    NAMES
a1b2c3d4e5f6   postgres:15   Up 30 seconds  0.0.0.0:5432->5432/tcp   pg15

# docker stats --no-stream
CONTAINER ID   NAME   CPU %   MEM USAGE / LIMIT   MEM %
a1b2c3d4e5f6   pg15   0.02%   38.5MiB / 512MiB    7.52%

# docker inspect --format
Memory: 536870912, RestartPolicy: unless-stopped

❓ FAQ

📖 Summary

• docker run = Create and start a container; this is the most essential Docker command
• -d Runs as a background service; -it Interactive debugging; the two are mutually exclusive
• Port Mapping -p host:container Exposes Container Services to the Host
• --rm is used for automatic cleanup of temporary tasks; --restart is used for automatic service recovery
• --memory / --cpus Limit resources to prevent a single container from using up all the host's resources
• Containers have a complete state lifecycle: Created → Running → Paused → Stopped → Deleted

📝 Exercises

1. Basic Exercise (Difficulty: ⭐): Start an Nginx container mapped to port 8080 on your local machine, then access it via a browser to verify that the page displays correctly.
2. Advanced Problem (Difficulty ⭐⭐): Launch an interactive Ubuntu container, run apt update && apt install -y curl inside the container, and then use curl to access a web page.
3. Challenge (Difficulty: ⭐⭐⭐): With the container’s memory limited to 256MB, run a stress-testing tool (such as progrium/stress) and observe whether the container is killed by an OOM (Out of Memory) error when memory is exceeded (Hint: docker events --filter event=oom).

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us