How to Use docker container run to Launch and Customize Containers
Docker operates applications inside containers — lightweight, isolated environments that package software together with all required dependencies and configuration. Unlike traditional virtual machines, containers do not rely on a dedicated guest operating system; instead, they share the underlying host kernel. This design results in faster startup times and lower resource overhead. The docker container run command is the primary mechanism for starting containers from images, applying runtime settings, and creating isolated processes.
This guide describes how to work with docker container run to start containers using custom parameters, including naming containers, running in detached mode, publishing ports, mounting volumes, and automatically removing containers with --rm. It also includes reference tables detailing crucial flags for handling networking, storage, resources, and container health checks.
The Short Answer Version
# Run a container interactively from an image
$ docker container run -it ubuntu
# Run a container in the background
$ docker container run -d nginx
# Run and name the container
$ docker container run --name myapp alpine
# Run and publish container port 80 to host port 8080
$ docker container run -p 8080:80 nginx
# Mount a volume into the container
$ docker container run -v $(pwd):/data alpine
# Run and remove container after it exits
$ docker container run --rm busybox echo "done"
Each example demonstrates a primary use case of docker container run, including naming, networking, volume mounting, interactive usage, and cleanup behavior.
General Options for docker container run
| Option | Description | Example |
|---|---|---|
| -d, –detach | Runs the container in detached mode. | -d |
| –name | Assigns a custom name to the container. | –name my-nginx |
| –rm | Automatically removes the container after exit. | –rm |
| -e, –env | Sets an environment variable. | -e NODE_ENV=production |
| –env-file | Loads environment variables from a file. | –env-file ./env.list |
| –entrypoint | Overrides the image’s entrypoint. | –entrypoint /bin/sh |
| -t, –tty | Allocates a TTY for interactive operations. | -it |
| -i, –interactive | Keeps STDIN open for interaction. | -it |
| –workdir, -w | Sets the working directory inside the container. | –workdir /usr/src/app |
Networking Options for docker container run
| Option | Description | Example |
|---|---|---|
| -p, –publish | Maps a container port to a host port. | -p 8080:80 |
| -P, –publish-all | Exposes all container ports to random host ports. | -P |
| –network | Connects the container to a custom Docker network. | –network backend-net |
| –add-host | Adds custom DNS entries to /etc/hosts. |
–add-host db.local:10.0.0.5 |
| –dns | Specifies DNS servers for the container. | –dns 1.1.1.1 |
Storage Options for docker container run
| Option | Description | Example |
|---|---|---|
| -v, –volume | Mounts a host path or volume inside the container. | -v /data:/app/data |
| –mount | Mounts storage via structured syntax. | –mount type=bind,src=/data,dst=/app |
| –tmpfs | Creates an in-memory filesystem. | –tmpfs /app/cache |
| –read-only | Sets the container filesystem to read-only. | –read-only |
Resource Management Options
| Option | Description | Example |
|---|---|---|
| –cpus | Limits CPU core usage. | –cpus 2 |
| –memory, -m | Defines memory limit. | -m 512m |
| –memory-swap | Sets memory+swap limit. | –memory-swap 1g |
| –oom-kill-disable | Prevents OOM kill. | –oom-kill-disable |
| –pids-limit | Restricts process count. | –pids-limit 100 |
Security Options
| Option | Description | Example |
|---|---|---|
| –user | Runs the container under a specific UID/GID. | –user 1000:1000 |
| –cap-add / –cap-drop | Modifies kernel capabilities. | –cap-drop NET_RAW |
| –security-opt | Defines security profiles. | –security-opt seccomp=./profile.json |
| –privileged | Grants full host-level permissions. | –privileged |
Container Health Options
| Option | Description | Example |
|---|---|---|
| –health-cmd | Runs a health check command. | –health-cmd “curl -f http://127.0.0.1/” |
| –health-interval | Defines time between checks. | –health-interval 30s |
| –health-retries | Specifies failure threshold. | –health-retries 3 |
| –no-healthcheck | Disables image-defined checks. | –no-healthcheck |
Additional Options
| Option | Description | Example |
|---|---|---|
| –restart | Configures restart behavior. | –restart always |
| –log-driver | Specifies container logging backend. | –log-driver json-file |
| –pull | Controls when Docker pulls images. | –pull always |
Run Container Under Specific Name
Use the --name flag to assign a custom name to a container. This helps with automation, logs, and operational management. Without naming, Docker generates a random identifier such as frosty_morse.
Container names must begin with an alphanumeric character and can include letters, digits, underscores, periods, and hyphens.
Command Syntax
docker container run --name <container-name> [IMAGE]
--name <container-name>: Assigns the container name.[IMAGE]: The Docker image to run.
Command Demonstration
Create a BusyBox container named busybox_test.
$ docker container run --name busybox_test busybox
Create an Nginx container named web-server.
$ docker container run --name web-server nginx
Create an Ubuntu container named linux.
$ docker container run --name linux ubuntu
Create a named container my-nginx and run it in detached mode.
$ docker container run --name my-nginx -d nginx
Verify running containers.
$ docker container ls
Display logs from my-nginx.
$ docker container logs my-nginx
Rename my-nginx to my-nginx-2.
$ docker container rename my-nginx my-nginx-2
List containers to confirm the updated name.
$ docker container ls
Output:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
dbbe80f32d93 nginx “/docker-entrypoint.…” 20 seconds ago Up 20 seconds 80/tcp my-nginx-2
Run Container in Background (Detached Mode)
By default, Docker executes containers in the foreground and streams their output to your terminal. To run a container in the background, use the -d flag (detached mode). This is ideal for services that need to remain active, such as web servers or background processes.
Command Syntax
docker container run -d [IMAGE]
-d: Runs the container in detached mode.[IMAGE]: The image to start (e.g., nginx, busybox).
Command Demonstration
Run an Nginx container in detached mode:
$ docker container run --name nginx-bg -d nginx
View real-time logs:
$ docker container logs -f nginx-bg
Open a shell session inside the container:
$ docker container exec -it nginx-bg bash
Run a command inside the container:
root@<container_id>:/# date
Output:
Fri Jun 27 11:22:47 UTC 2025
Exit the shell:
root@<container_id>:/# exit
Run Container and Publish Container Ports
Use the -p or --publish flag with docker container run to expose a container’s internal ports to the host. Publishing ports enables external access to containerized services, such as HTTP servers or APIs.
Only inbound connections require published ports. Containers can still make outbound connections without publishing.
Command Syntax
docker container run -p [IP:]<host_port>:<container_port> [IMAGE]
-p: Publishes container ports to the host.[IP:]: (Optional) Bind the port to a specific host interface.<host_port>: Port exposed on the host.<container_port>: Internal container port.[IMAGE]: The image (e.g., nginx, busybox).
Command Demonstration
Map container port 80 to host port 8080:
$ docker container run -p 8080:80 nginx
Map host port 8080 to container port 1234 (UDP):
$ docker container run -p 8080:1234/udp busybox
Limit accessibility to localhost only:
$ docker container run -p 127.0.0.1:8080:80 nginx
Bind container port 80 to host port 80:
$ docker container run -p 80:80 nginx
Expose both HTTP and HTTPS ports:
$ docker container run -p 80:80 -p 443:443 nginx
Command Application
Run an Nginx container and expose port 8080 publicly:
$ docker container run -d -p 8080:80 nginx
Test from a remote machine (replace with your server’s IP):
$ curl http://<SERVER-IP>:8080
Restrict access to localhost:
$ docker container run -d -p 127.0.0.1:8081:80 nginx
Verify local access works:
$ curl http://127.0.0.1:8081
Verify remote access fails (expected timeout):
$ curl http://<SERVER-IP>:8081
Run Container With Mounted Host Volume
By default, containers operate independently of the host filesystem. To share data—such as configuration files, static web assets, or database content—you can mount a host directory into the container using the -v flag.
Command Syntax
docker container run -v <host_path>:<container_path>[:options] [IMAGE]
-v: Mounts a host directory.<host_path>: Absolute path on the host.<container_path>: Mount target inside the container.[:options]: Optional settings such asro(read-only).[IMAGE]: The Docker image to use.
Command Demonstration
Mount a host directory with full read-write access:
$ docker container run -v /home/linuxuser/data:/data busybox
Mount the same directory as read-only:
$ docker container run -v /home/linuxuser/data:/data:ro busybox
Command Application
The following example shows how to build a simple static web server using Nginx and host-mounted content.
Create a directory for static web files:
$ mkdir /home/linuxuser/webdata
Navigate into that directory:
$ cd /home/linuxuser/webdata
Create an HTML file:
$ cat <<EOF > index.html
<!DOCTYPE html>
<html>
<head><title>centron Greeting</title></head>
<body><h1>Greetings from centron</h1></body>
</html>
EOF
Run an Nginx container that mounts the website files:
$ docker container run -d -p 8082:80 -v /home/linuxuser/webdata:/usr/share/nginx/html:ro nginx
Confirm the container is serving the page:
$ curl http://127.0.0.1:8082
Output:
<!DOCTYPE html>
<html>
<head><title>centron Greeting</title></head>
<body><h1>Greetings from centron </h1></body>
</html>
Mounted directories remain intact even after the container is removed. Any modifications to files inside /usr/share/nginx/html appear directly in /home/linuxuser/webdata on the host.
Run Docker Container and Automatically Remove It After Exit
By default, containers remain on the system even after they have stopped. Using the --rm flag with docker container run ensures the container is immediately removed after it finishes running. This option is ideal for temporary tasks, test runs, or script-like operations.
Command Syntax
docker container run --rm [IMAGE] [COMMAND]
--rm: Deletes the container as soon as it exits.[IMAGE]: The image to run.[COMMAND]: Command to run inside the container.
Command Demonstration
Run a container that prints “Hello, world” and removes itself afterwards:
$ docker container run --rm busybox echo "Hello, world"
Run a container that sleeps for five seconds, then exits and deletes itself:
$ docker container run --rm busybox sleep 5
Run an Ubuntu container that prints output and then removes itself:
$ docker container run --rm ubuntu bash -c "echo Done && date"
Command Application
Here is a demonstration of how --rm prevents unused containers from accumulating on your system.
Run a temporary BusyBox container using --rm:
$ docker container run --name busybox --rm busybox echo "Temporary container"
Confirm the container no longer exists:
$ docker container ls -a
The container does not appear in the list because Docker removed it automatically after execution.
Run the same example without --rm:
$ docker container run --name busybox busybox echo "Persistent container"
List all containers again:
$ docker container ls -a
Output:
CONTAINER ID IMAGE COMMAND CREATED STATUS NAMES
9f5d3cc7bb3e busybox “echo ‘Persistent co…’” 5 seconds ago Exited (0) 5 seconds ago busybox
This container remains on the system in the Exited state and must be removed manually using docker container rm.
Conclusion
This article explained how to launch containers using the docker container run command. You learned how to name containers, run them in detached mode, publish internal ports, mount host directories, and automatically clean up containers using --rm. You also reviewed important flags related to networking, storage, resource allocation, security, and health monitoring.
Together, these capabilities form the basis for building portable, flexible, and reproducible container workflows. For a broader overview and extended examples, refer to the official Docker documentation.
