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...]

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!"

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

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"

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

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

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

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

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

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

Command	Description
docker run ubuntu echo "Hello"	Run a one-off command in an Ubuntu container
docker run -it ubuntu bash	Run an interactive bash shell
docker run -d --name my_nginx -p 8080:80 nginx	Run an NGINX web server in detached mode
docker run --rm ubuntu ls	Automatically remove the container after it stops
docker run -e VAR=value ubuntu printenv	Run with environment variables
docker run -v /host/data:/container/data ubuntu	Bind a host directory as a volume
docker run --cpus=1.0 --memory=512m ubuntu	Limit CPU and memory usage
docker run --network=my_network nginx	Connect to a custom network
docker run --restart always nginx	Set a restart policy

---

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.

---