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 Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.