docker-run

Run command in a new container from a tagged image

$ docker run [image:tag] [command]

$ docker run [[-d|--detach]] [image] [command]

$ docker run --rm [[-i|--interactive]] [[-t|--tty]] [image] [command]

$ docker run [[-e|--env]] '[variable]=[value]' [[-e|--env]] [variable] [image] [command]

$ docker run [[-v|--volume]] [/path/to/host_path]:[/path/to/container_path] [image] [command]

$ docker run [[-p|--publish]] [host_port]:[container_port] [image] [command]

$ docker run --entrypoint [command] [image]

$ docker run --network [network] [image]

docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

--detach / -d
    Run container in the background, printing new container ID.

--interactive / -i
    Keep STDIN open even if not attached, useful for interactive processes.

--tty / -t
    Allocate a pseudo-TTY, often used with -i for interactive shell sessions.

--name
    Assign a specific name to the container, making it easier to reference.

--publish / -p :
    Publish a container's port(s) to the host, mapping specified ports.

--volume / -v :
    Mount a file or directory from the host into the container for persistent storage.

--env / -e
    Set environment variables inside the container.

--rm
    Automatically remove the container when it exits, useful for temporary containers.

--network
    Connect the container to a specific Docker network (e.g., host, bridge, or custom).

--restart
    Define the container's restart policy (e.g., no, on-failure, always, unless-stopped).

--entrypoint
    Override the default ENTRYPOINT of the image.

--workdir
    Set the working directory inside the container for the primary command.

--user [:]
    Run the command as a specified user or UID (and optional group) inside the container.

--hostname
    Set the container's hostname.

The docker run command is fundamental to Docker, enabling users to create and start a new container from a specified Docker image. An image acts as a lightweight, standalone, executable package that includes everything needed to run a piece of software, including the code, a runtime, system tools, system libraries, and settings.

When docker run is executed, it provisions a new, isolated environment (the container) based on the image's blueprint. This container runs the command specified in the image or overridden by the user, providing process isolation and resource management. By default, containers are ephemeral, meaning any changes made inside them are lost once they stop, unless volumes are used for persistent storage.

docker run is highly versatile, supporting a wide array of options to configure networking, expose ports, mount directories, set environment variables, limit resources, and define container lifecycle behavior, making it the primary tool for deploying and managing containerized applications.

• Data Persistence: By default, container data is lost when the container is removed. Use --volume to persist data outside the container's lifecycle, ensuring data survives container restarts or removals.
• Security: Running containers with --privileged or mounting sensitive host paths can introduce significant security risks. Always follow the principle of least privilege, granting only necessary permissions.
• Resource Consumption: Containers can consume significant host resources (CPU, memory, disk) if left unchecked. Use options like --memory and --cpus to limit resource usage and prevent host system performance degradation.
• Image Specificity: The behavior of docker run heavily depends on the ENTRYPOINT and CMD instructions defined within the Docker image. Understanding how these interact and how they can be overridden is crucial for predictable container execution.

By default, containers connect to a bridge network, allowing communication with other containers on the same bridge and the host. Options like --network allow connecting to custom user-defined networks, running on the host network (sharing the host's network stack), or isolating the container entirely (none network) for specialized use cases. User-defined networks provide better isolation and name resolution for services.

In a Dockerfile, ENTRYPOINT defines the primary command that will execute when the container starts, acting as the executable. CMD provides default arguments to the ENTRYPOINT or an executable if no ENTRYPOINT is specified. docker run allows overriding both: the [COMMAND] argument passed directly to docker run overrides the image's CMD, while --entrypoint explicitly overrides the image's ENTRYPOINT itself.

When you execute docker run, Docker first checks if the specified image is available locally. If not, it attempts to pull it from a configured registry (like Docker Hub). The --pull option (with policies like always, missing, or never) allows explicit control over this behavior, ensuring you always use the latest image, only pull if missing, or avoid network requests entirely for local-only images.

Docker emerged around 2013, quickly revolutionizing application deployment and portability. The docker run command has been central to this revolution from its inception, providing the core functionality for executing containerized applications. Its development has mirrored the evolution of Docker itself, incorporating new features like advanced networking, volume management, and resource controls, continually enhancing its capabilities to meet the demands of modern cloud-native architectures and microservices. It remains the most frequently used command for direct container interaction, serving as the gateway to containerized environments.

docker build(1): Build an image from a Dockerfile., docker ps(1): List running containers., docker stop(1): Stop one or more running containers gracefully., docker rm(1): Remove one or more containers., docker images(1): List Docker images stored locally., docker exec(1): Run a command in a running container (e.g., to debug or inspect)., docker compose(1): Define and run multi-container Docker applications using a YAML file.