23.3d Running containers: docker run flags (--rm, -d, -p, -v, --name, --network)¶

🧭 Context Introduction¶

When you run an AI workload—whether it's training a model on an NVIDIA GPU or serving inference with Triton—you'll use the docker run command constantly. This command is your primary tool for launching containers. However, a plain docker run is rarely enough. You need flags to control how the container behaves, how it connects to the outside world, and how it manages resources.

For new engineers, think of these flags as switches on a control panel. Each flag changes one specific behavior of your container. Understanding these six essential flags will let you run almost any AI container correctly.

⚙️ The Six Essential Flags — At a Glance¶

🛠️ Flag-by-Flag Breakdown¶

1. 🧹 --rm (Auto-Remove)¶

What it does: When the container stops running, Docker automatically deletes it.

Why use it: AI training jobs often run once and finish. Without --rm, every finished container stays on your disk as a "stopped" container. Over time, these accumulate and waste space.

How to think about it: Use --rm for short-lived, disposable containers like a quick training run or a data preprocessing job. Do not use it for containers you want to keep around (like a Jupyter server you restart often).

2. 🎭 -d (Detached Mode)¶

What it does: Runs the container in the background. Your terminal prompt returns immediately.

Why use it: AI workloads can run for hours or days. Without -d, your terminal is locked to that container's output. With -d, you can close the terminal, start other work, or even log out—the container keeps running.

How to think about it: Use -d for long-running services like a model serving endpoint or a training job you want to monitor later with docker logs.

3. 🔌 -p (Port Mapping)¶

What it does: Maps a port on your host machine to a port inside the container.

Why use it: Containers have their own internal network. Without -p, nothing outside the container can reach services running inside it. For AI, this is critical for: - Accessing Jupyter notebooks running inside a container - Reaching a Triton Inference Server endpoint - Connecting to a training dashboard like TensorBoard

How to think about it: The format is host_port:container_port. For example, mapping host port 8888 to container port 8888 lets you open http://localhost:8888 in your browser to reach Jupyter.

4. 📂 -v (Volume Mount)¶

What it does: Mounts a directory from your host machine into the container's filesystem.

Why use it: Containers are ephemeral—when they're deleted, all data inside them is gone. With -v, you keep your datasets, trained models, and code on your host machine. The container can read and write to these mounted directories as if they were inside the container.

How to think about it: The format is host_path:container_path. For example, mounting /home/user/data to /workspace/data means the container sees your datasets at /workspace/data.

5. 🏷️ --name (Container Name)¶

What it does: Gives your container a specific, memorable name instead of a random one like hungry_curie.

Why use it: When you run multiple containers, you need to manage them. With a name, you can: - Stop a container using its name instead of a long ID - View logs for a specific container - Remove a container without guessing which one it is

How to think about it: Choose descriptive names like triton-server, training-job-1, or jupyter-lab. Names must be unique while the container exists.

6. 🌐 --network (Network Mode)¶

What it does: Connects your container to a specific Docker network.

Why use it: By default, containers run on a bridge network. For AI workflows, you often need: - Containers to communicate with each other (e.g., a training container talking to a database) - Access to host-only resources - Isolation from other containers

How to think about it: Common values are: - bridge (default) — basic network for standalone containers - host — container shares the host's network stack (faster but less isolated) - none — no network access (for security-sensitive workloads)

📊 Visual Representation: Docker Run Lifecycle Container States¶

This flowchart displays container state changes during execution: from creation, to running, to exit.

🧪 Putting It All Together — A Real AI Scenario¶

Imagine you want to run an NVIDIA Triton Inference Server container that: - Uses your GPU - Loads models from your host machine - Serves on port 8000 - Runs in the background - Cleans up after itself - Has a clear name

You would use these flags together in a single docker run command:

• --rm — auto-remove when done
• -d — run in background
• -p 8000:8000 — expose the inference endpoint
• -v /home/user/models:/models — share your model files
• --name triton-server — give it a clear name
• --network host — use host networking for best GPU performance

🕵️ Common Mistakes New Engineers Make¶

✅ Quick Reference Card¶

For your daily work, remember this checklist when running any AI container:

1. Will this container finish and be discarded? → Add --rm
2. Do I need my terminal back? → Add -d
3. Does this container serve a web interface or API? → Add -p
4. Do I need to access files from my host? → Add -v
5. Will I run multiple containers? → Add --name
6. Does this container need special networking? → Add --network

Master these six flags, and you'll be able to run any NVIDIA AI container—from PyTorch training to Triton inference—with confidence.