Docker commands Guide – docker run with examples

Here’s a complete tutorial on the docker run command, explaining what it does, how to use it, a comprehensive list of examples, and use cases.

What is docker run?

docker run is the most fundamental Docker command. It creates and starts a new container from a Docker image. You can customize how the container runs by passing options like port mapping, volume binding, environment variables, and network configurations.

Key Features:

• Creates and starts a container in one command.
• Can run interactive shells, background services, or one-off commands.
• Supports options for networking, resource limits, and volumes.
• Allows configuration of entry commands and arguments for the container.

Basic Syntax

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
Code language: CSS (css)

Common Options:

• -d: Run the container in detached mode (background).
• -it: Run the container in interactive mode with a TTY (for shells).
• --name: Assign a custom name to the container.
• -p: Map host ports to container ports.
• -v: Mount volumes for persistent storage.
• -e: Set environment variables.
• --rm: Automatically remove the container after it stops.
• --network: Connect the container to a custom network.

Examples of docker run

1. Run a Simple Container (Foreground Mode)

docker run ubuntu echo "Hello, Docker!"
Code language: PHP (php)

This runs a container using the ubuntu image and executes the echo command. The container stops immediately after printing the message.

2. Run a Container in Interactive Mode (Shell Access)

docker run -it ubuntu bash

This runs the ubuntu container and opens an interactive bash shell.

3. Run a Detached Container (Background Mode)

docker run -d --name my_nginx -p 8080:80 nginx
Code language: CSS (css)

This runs an nginx web server in the background, mapping port 8080 on the host to port 80 in the container.

4. Assign a Custom Name to the Container

docker run --name my_custom_name ubuntu sleep 100

This runs a container named my_custom_name.

5. Automatically Remove the Container After It Stops

docker run --rm ubuntu echo "Temporary container"
Code language: PHP (php)

The container is removed automatically once the command finishes.

6. Run a Container with Environment Variables

docker run -e ENV_VAR1=value1 -e ENV_VAR2=value2 ubuntu printenv

This sets and prints the environment variables inside the container.

7. Bind a Host Directory as a Volume

docker run -v /host/data:/container/data ubuntu ls /container/data
Code language: JavaScript (javascript)

This mounts the /host/data directory on the host to /container/data in the container.

8. Run a Container with Limited Resources (CPU and Memory)

docker run --memory="512m" --cpus="1.0" ubuntu stress --vm 1
Code language: JavaScript (javascript)

This limits the container to 512MB of RAM and 1 CPU core.

9. Connect a Container to a Custom Network

docker network create my_network
docker run --network my_network nginx

This connects the nginx container to my_network.

10. Run a Database with Persistent Storage

docker run -d --name my_mysql -e MYSQL_ROOT_PASSWORD=my-secret-pw -v mysql_data:/var/lib/mysql mysql
Code language: JavaScript (javascript)

This runs a MySQL container with a persistent volume (mysql_data) to store the database files.

11. Run a Container with Multiple Port Mappings

docker run -d -p 8080:80 -p 8443:443 nginx
Code language: CSS (css)

This maps port 8080 and 8443 on the host to port 80 and 443 in the container.

12. Run a Container with Custom DNS

docker run --dns=8.8.8.8 ubuntu ping google.com

This specifies 8.8.8.8 as the DNS server for the container.

13. Run a Container with an Alternate Command

docker run ubuntu ls /usr

This overrides the default command for the ubuntu image and runs ls /usr instead.

14. Restart Policy: Always Restart the Container

docker run --restart always nginx

This ensures the container restarts automatically if it stops.

15. Run a Container in Read-Only Mode

docker run --read-only ubuntu touch /tmp/test

This prevents the container from modifying the filesystem.

16. Run a GUI Application in a Container (Linux)

docker run -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix my-gui-app
Code language: JavaScript (javascript)

This runs a graphical application using the host’s display.

17. Debug a Failing Container

docker run -it --entrypoint /bin/sh my_app

This overrides the container’s entrypoint to open an interactive shell for debugging.

Use Cases for docker run

1. Web Servers and Microservices

• Deploy web servers like NGINX, Apache, or Node.js in isolated containers.
• Run microservices with separate containers for different components (database, caching, messaging).

2. Development Environments

• Use containers as isolated development environments with all dependencies pre-installed.
• Share development environments using Docker images.

3. Databases and Data Persistence

• Run databases like MySQL, PostgreSQL, or MongoDB in containers with persistent storage volumes.

4. CI/CD Pipelines

• Automate testing and deployments by running applications in Docker containers.
• Use docker run to execute tests in isolated environments.

5. Debugging and Troubleshooting

• Open interactive shells in containers for on-the-fly debugging.
• Run one-off commands to inspect the container’s state.

6. Batch Processing and Background Jobs

• Run data processing jobs, background tasks, or cron jobs in containers.
• Example: Data extraction, transformation, and load (ETL) tasks.

7. Network Simulation and Custom Networking

• Simulate network conditions using multiple Docker networks.
• Connect containers to custom networks for secure communication.

List of Common docker run Commands

Best Practices for Using docker run:

1. Use --rm for one-off tasks to avoid accumulating stopped containers.
2. Map ports carefully to avoid conflicts on the host machine.
3. Use environment variables (-e) for configuration instead of hardcoding values.
4. Limit resources (--cpus and --memory) to prevent containers from consuming excessive resources.
5. Mount volumes (-v) for persistent storage.
6. Combine with docker-compose for managing multi-container applications.

Common Errors and Solutions

1. “Image not found”
   → Ensure the image exists or pull it from Docker Hub: docker pull ubuntu
2. “Port already in use”
   → Use a different port for the container (-p 8081:80).
3. “Permission denied”
   → Ensure you have the necessary permissions or run with sudo.
4. “Container cannot connect to the internet”
   → Check the container’s network settings with docker network inspect.

Rajesh Kumar

I’m a DevOps/SRE/DevSecOps/Cloud Expert passionate about sharing knowledge and experiences. I have worked at Cotocus. I share tech blog at DevOps School, travel stories at Holiday Landmark, stock market tips at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow , and SEO strategies at Wizbrand.

Do you want to learn Quantum Computing?

Please find my social handles as below;

Rajesh Kumar Personal Website
Rajesh Kumar at YOUTUBE
Rajesh Kumar at INSTAGRAM
Rajesh Kumar at X
Rajesh Kumar at FACEBOOK
Rajesh Kumar at LINKEDIN
Rajesh Kumar at WIZBRAND

Rajesh Kumar DailyLogs