Docker run: Complete Guide to Running Containers in Linux

Introduction / Why This Matters

The docker run command is the primary tool for starting Docker containers. It takes a Docker image, creates a new container from it, and runs it with specified parameters. Understanding this command is the first and most crucial step in working with Docker. After completing this guide, you will be able to confidently run containers with web servers, databases, or any other software, configure networking, storage, and interactive access.

Prerequisites / Preparation

Before you begin, ensure that:

1. Docker Engine is installed and running. Check with docker --version. The output should show version 20.10 or newer.
2. Your user has permissions to manage Docker. This typically requires membership in the docker group. Check with groups $USER. If the docker group is missing, add your user (sudo usermod -aG docker $USER) and log out and back in.
3. You can pull images from Docker Hub. This works by default for public images (like nginx, ubuntu).

Step-by-Step Guide

Step 1: Basic Syntax and Running a Test Container

The simplest command invocation is: docker run <image_name>. Docker checks if the image exists locally. If not, it automatically pulls it from Docker Hub, creates a container, and runs the default command specified in the image's Dockerfile.

# Run the official test image
docker run hello-world

What happened: Docker downloaded the hello-world image and ran it. The container performed its task (printing a greeting) and then stopped.

Step 2: Interactive Execution and Working Inside a Container

To remain inside a container after launch (e.g., for a bash shell), use the -i (interactive) and -t (allocate a pseudo-TTY) flags.

# Run an Ubuntu image and enter the bash shell
docker run -it ubuntu:22.04 bash

What happened:

• -it — You connected to the container's terminal.
• ubuntu:22.04 — The specific image version.
• bash — The command to execute inside the container (overrides the image's CMD).

You will be at a command prompt inside the container. To exit, type exit. The container will stop.

Step 3: Background Operation and Port Forwarding

Often, containers (web servers, databases) need to run in the background (detached). The key flag is -d. To access a service from the host, port forwarding with -p is required.

# Run Nginx in the background, forwarding host port 8080 -> container port 80
docker run -d -p 8080:80 --name my-nginx nginx:latest

Flag breakdown:

• -d — Run in detached mode (returns the container ID).
• -p 8080:80 — Port mapping: host_port:container_port.
• --name my-nginx — Assigns a friendly name to the container (instead of a random ID).
• nginx:latest — The image to run.

Now Nginx is running inside the container. Open http://localhost:8080 in your browser — you will see the Nginx welcome page.

💡 Tip: To map all exposed container ports to random host ports, use -P (uppercase P).

Step 4: Mounting Volumes and Managing Data

By default, data inside a container disappears when the container is removed. To persist files on the host or share them between containers, use volumes or bind mounts.

# Run a container with the host's current directory mounted to /app inside the container
docker run -it -v "$(pwd)":/app ubuntu:22.04 bash

What happened: The directory from which you ran the command on the host is now accessible inside the container at /app. All changes in /app will be visible on the host and will persist after the container is restarted.

Step 5: Container Lifecycle Management

docker run creates and starts a new container. If a container already exists (stopped), use docker start/docker stop.

# Stop a running container by name
docker stop my-nginx

# Start a stopped container (with the same parameters)
docker start my-nginx

# List all containers (including stopped ones)
docker ps -a

# Remove a stopped container
docker rm my-nginx

⚠️ Important: Removing a container (rm) does not remove the image it was created from. Images are managed separately (docker image rm).

Verification Checklist

1. Container is running: Execute docker ps. Active containers (e.g., my-nginx) should be listed.
2. Service is accessible: For a web server, open the port specified with -p in your browser (http://localhost:8080). For a database, test the local connection.
3. Data persists: If you mounted a volume, create a file inside the container (touch /app/test.txt) and verify it exists in the corresponding directory on the host.
4. Container logs: Check logs for errors: docker logs <container_name_or_id>.

Troubleshooting

# Example diagnostic: run a shell in an already created container (if it stopped)
docker run -it --rm --entrypoint sh <image_name>