Before touching any command, it helps to be precise about what “running” actually creates.

An image is a read-only package containing an application and everything it needs to work: its code, its libraries, and a minimal slice of an operating system’s files. It never changes and never does anything on its own; it simply sits in storage, waiting. A container is what you get the moment the Docker Engine takes that image, adds one thin writable layer on top of it, and starts a real operating-system process from it. That process has its own private view of the file system, its own network address, and its own list of running programs, even though it is, underneath, an ordinary process on the host machine.

“Running a container” therefore means asking the Docker Engine to perform four things in order: make sure the image exists locally, prepare an isolated environment for it using Linux kernel features, start the image’s main program inside that environment, and then keep track of that process until it stops. All of this typically begins with one line typed into a terminal.

The simplest possible example

Typing docker run hello-world is enough to see the whole idea in miniature. Docker checks whether an image named hello-world already exists on the machine; if not, it downloads a tiny one from a public registry, starts a container from it, lets that container print a short friendly message to the screen, and then lets the container exit on its own because its job was only to print that one message. Nothing is left running afterward, yet a real container genuinely existed, however briefly.

It is worth pausing on why this single moment gets so much attention throughout this guide. Building an image is usually done once, then reused many times, but running that image happens over and over, on different machines, under different real-world conditions, sometimes thousands of times a day for a busy service. Every one of the small decisions made at that moment, whether a port is published, whether a volume is attached, whether a restart policy is set, is what actually determines how that particular running copy of the application behaves once real users, real traffic, or a real failure eventually reach it.

A handful of words appear constantly around running containers. Getting comfortable with them now makes every later chapter easier.

Reading a real command, piece by piece

A typical real-world command looks like this in spirit: run an image, give the container a name, publish a port, attach a volume, pass in an environment variable, set a restart policy, and run it in the background. Every one of those pieces is an independent option that can be mixed and matched, and the order mostly does not matter as long as the image name comes last. The rest of this guide walks through exactly what each of these pieces does underneath, one at a time.

Interactive versus non-interactive containers

Not every container is meant to run quietly in the background forever. Some are started specifically so a person can type commands into them directly, such as opening a temporary shell inside a fresh Linux image to experiment safely without touching the host machine at all. Running a container this way usually combines two separate options: one that keeps an input channel open so you can type into it, and another that allocates a proper interactive terminal so text formatting, colours and cursor movement behave the way they would in a normal terminal window. Without both together, the container either ignores everything you type or displays it in a broken, unreadable way. This interactive style is common for quick exploration and debugging, while detached mode, covered later in this guide, is what almost every long-running service actually uses in practice.

Typing one line hides a short relay race between several small, specialised programs.

flowchart LR
    CLI["Docker CLI: the docker run command"] -->|"REST API call"| API["Engine API"]
    API --> D["dockerd: the Docker daemon"]
    D -->|"checks local cache, pulls if missing"| REG[("Registry: Docker Hub or Amazon ECR")]
    D -->|"gRPC"| C["containerd: container supervisor"]
    C --> SH["containerd-shim: one per container"]
    SH --> R["runc: OCI runtime"]
    R --> P["Your application process"]

The Docker CLI, the docker command itself, does very little real work. It simply turns your typed options into a structured request and sends it to the Engine API, a set of agreed messages the rest of the system understands. That request usually travels over a local Unix socket, a special file used for programs on the same machine to talk to each other quickly and privately.

The daemon, whose process name is dockerd, receives the request and acts as the manager. Its first job is to check whether the image you asked for already exists locally; if not, it downloads, or pulls, the missing layers from a registry such as Docker Hub. Once the image is available, the daemon does not start the container itself. It delegates that job to containerd, an independent supervisor program that Kubernetes also uses directly. containerd, in turn, calls runc, a small program that follows the Open Container Initiative standard and does the actual low-level work of asking the Linux kernel to build an isolated space and launch your process inside it.

Once your process is running, runc’s job is finished and it exits, but a lightweight helper called the shim stays behind for as long as the container lives. The shim keeps the container’s input and output connected, and remembers its exit code the moment it stops, so that later commands like viewing logs still work correctly.

Why the chain is split into so many small pieces

It might seem simpler if one single program handled everything from receiving your command to running your process, and early container tools were sometimes built closer to that shape. Splitting the work across the daemon, containerd, the shim and runc instead brings two practical benefits that matter once a machine is running many containers at once, not just one. First, if the daemon itself needs to be restarted, perhaps to install an upgrade, the shim keeps every already-running container’s process alive and connected in the meantime, so a routine engine upgrade does not force every container on that machine to stop and restart along with it. Second, because each piece follows the same open Open Container Initiative standard at its boundary, other tools, including Kubernetes itself, can talk to containerd and runc directly without needing the Docker daemon at all, which is exactly why images built and tested using the Docker Engine continue to run correctly under those other systems.

The instant before your application code runs, the kernel quietly builds the walls that make a container feel like its own machine.

When runc is asked to start a container, it uses two ordinary Linux kernel features to construct the isolation everyone associates with containers. The first is the namespace, which gives the new process its own private view of one type of system resource. A process ID namespace makes the container’s first process appear as process number one from the inside, even though the host sees it under a completely different, much larger number. A network namespace gives the container its own network interface and IP address. A mount namespace gives it its own view of the file system, hiding the host’s real files unless they are deliberately shared in.

The second feature is the control group, or cgroup, which limits and measures how much processor time, memory and disk activity that process is allowed to use. If a memory limit is set and the container’s process tries to use more than its share, the kernel intervenes rather than letting it starve every other process on the machine.

flowchart TB
    Req["runc receives the start request"] --> NS["Create namespaces: PID, network, mount, hostname"]
    NS --> CG["Apply cgroup limits: CPU, memory, disk I/O"]
    CG --> FS["Assemble the file system from image layers plus one writable layer"]
    FS --> EXEC["Execute the container's main process inside this isolated space"]

Only after namespaces are created, cgroup limits are attached, and the file system is assembled from the image’s layers plus a fresh writable layer on top, does runc finally execute the container’s main command. From that point on, to the application itself, the machine appears to be entirely its own: its own process list, its own network card, its own root file system, even though every one of those things is, underneath, a carefully fenced-off slice of the same host the other containers are also running on.

A container is not simply “on” or “off.” It moves through several distinct states, and knowing them prevents a lot of confusion.

sequenceDiagram
    participant U as You
    participant CLI as Docker CLI
    participant D as dockerd
    participant C as containerd + runc
    U->>CLI: docker run -d --name web myapp
    CLI->>D: create and start container
    D->>D: pull image if not present locally
    D->>C: create container, then start it
    C-->>D: process running, PID assigned
    D-->>CLI: container ID returned
    CLI-->>U: prints container ID, returns control
    Note over C: container now in Running state

The five states, one by one

Stopping a container the polite way

When you ask Docker to stop a running container, it does not simply kill the process instantly. It first sends a termination signal, giving the application a short grace period, typically ten seconds by default, to save its work, close open connections, and shut itself down cleanly. Only if the process ignores this signal and the grace period expires does Docker forcibly kill it. An application that never listens for this polite request loses in-flight work on every single stop, restart, or deployment, which is why handling it correctly is considered a basic requirement for anything meant to run in production.

Docker’s run command supports dozens of options, but a small handful cover almost every real situation you will meet.

Restart policies compared

Labels: attaching your own metadata

Beyond the options above, Docker also lets you attach arbitrary labels to a container at run time, small key-and-value notes such as recording which team owns it, which environment it belongs to, or which version of an internal deployment tool created it. Labels do nothing to the running application itself; they exist purely so that other tools, and other people, can later filter, group or organise containers by these notes, for example listing every container labelled as belonging to a particular project across a busy shared server. Many monitoring and orchestration tools lean heavily on labels behind the scenes to automatically discover and organise the containers they manage, so developing the habit of labelling containers consistently pays off well beyond a single afternoon of manual commands.

A container’s own private network address is invisible to the outside world until you deliberately open a door to it.

By default, a newly run container is attached to a private virtual network called bridge and is handed its own internal IP address, similar to a home router assigning addresses to phones and laptops. Containers on the same network can reach each other using that internal address, and on a user-created network, they can also find each other simply by container name, because the engine runs a small internal DNS service for exactly this purpose.

That internal address, however, is not reachable from outside the host machine on its own. To let outside traffic in, you publish a port at run time, for example telling Docker that anything arriving at port 8080 on the host should be forwarded to port 80 inside the container. Behind the scenes, this quietly configures the host’s own firewall rules to perform that redirection automatically, for as long as the container is running.

flowchart LR
    Ext["Outside request to host:8080"] --> FW["Host firewall / NAT rule"]
    FW --> Br["Bridge network"]
    Br --> Ctr["Container's internal port 80"]
    Ctr2["A second container"] -->|"talks by container name via internal DNS"| Ctr
    Br -.-> Ctr2

Binding to a specific host address

By default, publishing a port makes it reachable on every network interface the host machine has, which on a server with more than one network card, or one connected to both a private internal network and the public internet, can quietly expose a service further than intended. A run-time option lets you bind a published port to one specific host address instead, for example only the machine’s internal, private network interface, so the same container remains reachable to trusted internal systems while staying completely invisible from the public internet. This one small detail is a common cause of unpleasant surprises during a security review, when a service everyone assumed was internal-only turns out to have quietly been reachable from outside all along, simply because a port was published without specifying which interface it should actually listen on.

Choosing a network mode when you run

By default, everything a container writes disappears the moment it is removed. Volumes are how you decide, on purpose, what should survive.

Every running container has its own thin, writable layer sitting on top of its image’s read-only layers. Anything the application writes there, unless told otherwise, lives only inside that one container. The moment the container is removed, that writable layer, and everything written to it, is deleted permanently along with it.

A volume is a storage location managed by the Docker Engine but kept independent of any single container’s writable layer. When you mount a volume into a container at run time, anything the application writes to that mounted location is really being saved into the volume, which continues to exist, fully intact, even after the container that used it is stopped, removed, or replaced entirely by a newer version built from an updated image.

Read-only mounts and shared mounts

A mounted volume or bind mount does not have to be writable at all. Marking a mount as read-only at run time lets a container read configuration files, reference data, or shared assets from that location while being completely unable to change or delete them, which is a simple and effective safeguard for any data a particular container should only ever consume rather than modify. The same physical volume can also be mounted, at the same time, into several different containers, some with write access and some marked read-only, which is exactly how a pattern like one container writing log files while a separate, more restricted container only reads and forwards them tends to be built in practice.

Two easily overlooked choices, how much of the machine a container may use and whether it runs attached to your terminal, quietly shape how reliable it is.

Without an explicit limit, a single container is free to use as much of the host’s memory and processor time as it can get. On a shared machine, one misbehaving container, perhaps stuck in a loop or leaking memory, can starve every other container running alongside it, or even crash the entire host. Setting a memory limit and a CPU limit when you run a container hands that container a fixed, guaranteed slice of the machine and, just as importantly, protects everyone else on that machine from it.

Separately, every container runs in one of two modes. Foreground mode keeps the container’s output streaming directly into your terminal and ties its life to that terminal session; closing the terminal, or pressing the interrupt key combination, normally stops the container too. Detached mode starts the container fully in the background and instantly returns your terminal to you, which is the mode almost every real service, anything meant to keep running after you walk away from your keyboard, actually needs.

Running everything in containers is not automatically the right answer for every situation. Weighing the honest trade-offs makes for better decisions.

Most of the flags available on docker run exist to make a container either safer or more dangerous. Knowing which is which matters.

Trusting what you run

Security at run time also depends heavily on decisions made long before the run command is ever typed: which image was chosen in the first place. Pulling and running an image from an unfamiliar source, without checking who published it or whether it has been scanned for known vulnerabilities, means trusting a stranger’s software with real access to your machine’s kernel through the shared namespaces and cgroups described earlier in this guide. Preferring official, actively maintained images, verifying an image’s digest when it matters that you run exactly the version you tested, and keeping images patched and rebuilt regularly are all run-time-adjacent habits that meaningfully reduce risk, even though they happen slightly before the run command itself.

Once a container is running unattended, you need a way to know it is actually healthy, not just technically still alive.

Every container’s standard output and standard error, the two text streams a program normally prints, are captured automatically by the engine’s logging driver. The simplest way to inspect them is a command that reads a specific container’s captured output directly, optionally following it live as new lines arrive, which is often the very first thing to check when something seems wrong with a running container.

For a quick live snapshot of resource usage, a separate command shows processor use, memory use, network traffic and disk activity for one or more running containers at once, drawn straight from the same cgroup counters that were set up when the container was started. This is ideal for a fast manual check; production systems typically export the same numbers continuously to a dedicated metrics platform so trends can be graphed and alerts raised automatically.

As more containers are run side by side, a single user request often passes through several of them before a response is finally sent back, one container handling authentication, another handling the actual business logic, another writing to a database. Distributed tracing attaches one shared identifier to a request as it travels across this chain of containers, so that when something along the way is unusually slow or fails outright, an engineer can see the exact path that single request took, and exactly how long each container spent on it, instead of manually comparing timestamps across several separate log files and guessing at which entries actually belong together.

Certain ways of running containers work reliably again and again. Others cause the same headaches under a different name every time.

A short, practical checklist that resolves most of the problems people run into the first time they run containers for real.

Cleaning up after yourself

Every container that is run and later stopped, but never removed, continues to sit on disk holding its own writable layer, its logs, and its configuration, contributing to a slow, easy-to-miss build-up of unused disk space on any machine used for regular development or testing. A periodic cleanup command lets you remove every stopped container, unused network, and dangling image in one step, freeing that space back up. On a shared development or staging machine, agreeing on a simple habit, such as running this cleanup at the end of each day or automatically on a schedule, prevents the slow, quiet accumulation of forgotten containers from ever becoming a real problem that someone has to investigate later.

The choices covered in this guide are made, at enormous scale, by some of the best-known technology companies in the world, every single day.

Whether it is one developer running a single container on a laptop or a global company running millions of them, the same basic run-time decisions covered in this guide, naming, networking, persistence, restart behaviour, resource limits, and security, are exactly what determine whether a container behaves reliably or becomes a source of quiet, hard-to-diagnose problems later.