✦ For everyone, free.

Practical knowledge for real and everyday life

Home

20.1.1.3 Docker Run Basics

A focused guide to Docker Run Basics, connecting core concepts with practical Docker and container operations.

docker run is the most fundamental Docker command. It creates a new container from an image and starts it. Every interaction with a running container begins with this command, and understanding its anatomy — its syntax, the sequence of operations it performs, and its most common flags — is the foundation of practical Docker use.

What docker run Does

When you execute docker run, Docker performs these steps in order:

  1. Checks whether the specified image exists locally.
  2. If the image is not local, pulls it from the configured registry (Docker Hub by default).
  3. Creates a new container from the image, allocating a writable filesystem layer and assigning a container ID.
  4. Configures the container's network, volumes, environment variables, and resource limits based on the flags provided.
  5. Starts the container's main process.
  6. Connects the terminal to the container's stdin, stdout, and stderr (unless -d is specified).

Basic Syntax

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

The image name is the only required argument. Everything else is optional.

Running a Simple Container

docker run hello-world

Pulls and runs the hello-world image, which prints a verification message and exits.

docker run ubuntu echo "hello from ubuntu"

Runs the ubuntu image, executes echo "hello from ubuntu" inside it, and exits. The container is created, used for one command, then stops.

Detached Mode: -d

By default, docker run attaches the terminal to the container. When the container process exits, or when you press Ctrl+C, the container stops. For long-running services, use detached mode:

docker run -d nginx:latest

The container starts in the background. Docker prints the full container ID and returns control to the shell immediately. The container continues running until explicitly stopped.

Interactive Mode: -it

To run a container with an interactive terminal:

docker run -it ubuntu bash
  • -i (interactive): Keeps stdin open, allowing you to type input.
  • -t (tty): Allocates a pseudo-terminal, giving a proper terminal experience.

You get a shell prompt inside the container. Type exit to leave and stop the container.

Naming Containers: --name

Without --name, Docker assigns a random two-word name. To specify a name:

docker run -d --name my_nginx nginx:latest

Named containers are easier to reference in subsequent commands. If you try to use the same name twice without removing the first container, Docker returns an error.

Port Publishing: -p

To make a container port accessible from the host:

docker run -d -p 8080:80 nginx:latest

Format: -p <host_port>:<container_port>

The container listens on port 80 internally; port 8080 on the host machine maps to it. Accessing http://localhost:8080 in a browser reaches the nginx server.

To bind to a specific host IP:

docker run -d -p 127.0.0.1:8080:80 nginx:latest

This restricts access to localhost only, not from other machines on the network.

Environment Variables: -e

Pass environment variables to the container at startup:

docker run -d -e MY_VAR=hello -e DB_HOST=database my_app

To read variables from a file:

docker run -d --env-file .env my_app

Volume Mounts: -v

To persist data or share files between the host and the container:

Bind mount (host path to container path):

docker run -d -v /host/data:/app/data nginx:latest

Named volume:

docker run -d -v my_data:/app/data nginx:latest

Named volumes are managed by Docker and persist beyond the container's lifetime.

Removing on Exit: --rm

For containers that run a single task and should be automatically cleaned up:

docker run --rm alpine sh -c "echo done"

The container is removed immediately after it exits. No manual docker rm needed.

Resource Limits

To prevent a container from consuming excessive host resources:

docker run -d --memory 512m --cpus 0.5 nginx:latest
  • --memory 512m: Container processes cannot use more than 512 megabytes of RAM.
  • --cpus 0.5: Container processes get at most half of one CPU core.

Overriding the Default Command

The image defines a default command (CMD or ENTRYPOINT) to run. You can override it by providing a command after the image name:

docker run ubuntu ls /etc

Instead of starting bash (ubuntu's default), this runs ls /etc and exits.

For images with an ENTRYPOINT, the provided command is appended as arguments:

docker run --rm alpine ping -c 4 8.8.8.8

Anatomy of a Complete Example

docker run \
  -d \
  --name postgres_db \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=mysecret \
  -v postgres_data:/var/lib/postgresql/data \
  --memory 1g \
  --cpus 1.0 \
  postgres:15

This single command:

  • Runs the container in the background (-d).
  • Names it postgres_db.
  • Maps port 5432.
  • Sets the required password environment variable.
  • Mounts a named volume for persistent data.
  • Limits memory to 1GB and CPU to 1 core.
  • Uses the postgres:15 image.

This is the pattern used for running real application services with Docker.

Related content