IMAGE -->|"docker run<br/>as dynamo user"| CONTAINER
end
TERM -->|"SSH Connection"| DIR
...
...
@@ -260,9 +260,9 @@ File Structure:
- Local dynamo repo mounts to `/workspace`
- Python venv in `/opt/dynamo/venv`
- Build artifacts in `/workspace/target`
- Hugging Face cache preserved between sessions (either mounting your host .cache to the container, or your `HF_HOME` to `/home/ubuntu/.cache/huggingface`)
- Bash memory preserved between sessions at `/home/ubuntu/.commandhistory` using docker volume `dynamo-bashhistory`
- Precommit preserved between sessions at `/home/ubuntu/.cache/precommit` using docker volume `dynamo-precommit-cache`
- Hugging Face cache preserved between sessions (either mounting your host .cache to the container, or your `HF_HOME` to `/home/dynamo/.cache/huggingface`)
- Bash memory preserved between sessions at `/home/dynamo/.commandhistory` using docker volume `dynamo-bashhistory`
- Precommit preserved between sessions at `/home/dynamo/.cache/precommit` using docker volume `dynamo-precommit-cache`
## Documentation
...
...
@@ -397,8 +397,8 @@ docker volume prune -f
**Note:** This resets bash history and pre-commit cache.
@@ -39,23 +39,23 @@ The `build.sh` and `run.sh` scripts are convenience wrappers that simplify commo
These targets are specified with `build.sh --target <target>` and correspond to Docker multi-stage build targets defined in the Dockerfiles (e.g., `FROM somebase AS <target>`). Some commonly used targets include:
-`runtime` - For running pre-built containers without development tools (minimal size)
-`dev` - For development (inferencing/benchmarking/etc, runs as root user)
-`local-dev` - For development with local user permissions matching host UID/GID. This is useful when mounting host partitions (with local user permissions) to Docker partitions.
-`runtime` - For running pre-built containers without development tools (minimal size, runs as non-root `dynamo` user with UID 1000 and GID 0)
-`dev` - For development (inferencing/benchmarking/etc, runs as root user for maximum flexibility)
-`local-dev` - For development with local user permissions matching host UID/GID. This is useful when mounting host partitions (with local user permissions) to Docker partitions. The `dynamo` user UID/GID is remapped to match the host user.
Additional targets are available in the Dockerfiles for specific build stages and use cases.
| **DYNAMO_HOME** | ❌ Not set | `/opt/dynamo` | ❌ Not set | `/opt/dynamo` | `/workspace` ✅ **OVERRIDE** | `/workspace` (inherited) |
| **WORKSPACE_DIR** | ❌ Not set | ❌ Not set | ❌ Not set | ❌ Not set | `/workspace` | `/workspace` (inherited) |
| **CARGO_TARGET_DIR** | ❌ Not set | `/opt/dynamo/target` | ❌ Not set | ❌ Not set | `/workspace/target` ✅ **OVERRIDE** | `/workspace/target` (inherited) |
-`dev` target: System-wide at `/usr/local/rustup` and `/usr/local/cargo` (suitable for root)
-`local-dev` target: User-specific at `/home/ubuntu/.rustup` and `/home/ubuntu/.cargo` (proper UID/GID ownership)
-`local-dev` target: User-specific at `/home/dynamo/.rustup` and `/home/dynamo/.cargo` (proper UID/GID ownership)
**3. Build Artifacts Location:**
-`base→dev`: `/opt/dynamo/target` - Build artifacts with installed package
...
...
@@ -112,11 +112,21 @@ From `Dockerfile.local_dev`, the Rust toolchain is moved to user home because:
The Python venv ownership is also updated via rsync in local-dev to match the user's UID/GID, ensuring package installation permissions work correctly.
**6. Non-Root User Architecture:**
Dynamo containers implement a multi-stage user strategy:
-**runtime stage**: Runs as non-root `dynamo` user (UID 1000, GID 0) for production workloads
-**dev stage**: Runs as root for maximum development flexibility (builds on runtime but switches to root)
-**local-dev stage**: Runs as `dynamo` user with UID/GID matched to host user for safe file system operations
-**Security**: Runtime and local-dev use non-root execution to reduce attack surface
-**File Ownership**: All application files, virtual environments, and build artifacts are owned by `dynamo:root` (1000:0) in runtime stage
-**Environment Setup**: Launch banner moved to `/opt/dynamo/.launch_screen` (shared across all users) and venv activation configured in `/etc/bash.bashrc` for system-wide availability. This replaces the previous per-user `~/.launch_screen` and `~/.bashrc` approach.
## Usage Guidelines
-**Use dev + `run.sh`**: for command-line testing. Runs as root user
-**Use local-dev + `run.sh`**: for command-line development and Docker mounted partitions using your local user ID. Add `-it` flag for interactive sessions
-**Use local-dev + Dev Container**: VS Code/Cursor Dev Container Plugin, using your local user ID
-**Use runtime target**: for production deployments. Runs as non-root `dynamo` user (UID 1000, GID 0) for security
-**Use dev + `run.sh`**: for command-line testing and inferencing. Runs as root for maximum flexibility
-**Use local-dev + `run.sh`**: for command-line development and Docker mounted partitions. Runs as `dynamo` user with UID/GID matched to your local user. Add `-it` flag for interactive sessions
-**Use local-dev + Dev Container**: VS Code/Cursor Dev Container Plugin, using `dynamo` user with UID/GID matched to your local user
## Example Commands
...
...
@@ -125,13 +135,22 @@ The Python venv ownership is also updated via rsync in local-dev to match the us
run.sh ...
```
### 2. local-dev + `run.sh` (runs as the local user):
### 2. local-dev + `run.sh` (runs as dynamo user with matched host UID/GID):
Use VS Code/Cursor Dev Container Extension with devcontainer.json configuration
Use VS Code/Cursor Dev Container Extension with devcontainer.json configuration. The `dynamo` user UID/GID is automatically matched to your local user.
### 4. runtime target (runs as non-root dynamo user):
```bash
# Build runtime image
./build.sh --framework vllm --target runtime
# Run runtime container
./run.sh --image dynamo:latest-vllm-runtime
```
## Build and Run Scripts Overview
...
...
@@ -158,7 +177,7 @@ The `build.sh` script is responsible for building Docker images for different AI
# Build vLLM dev image called dynamo:latest-vllm (default). This runs as root and is fine to use for inferencing/benchmarking, etc.
./build.sh
# Build both development and local-dev images (integrated into build.sh). While the dev image runs as root, the local-dev image will run as the local user, which is useful when mounting partitions. It will also contain development tools.
# Build both development and local-dev images (integrated into build.sh). While the dev image runs as root, the local-dev image will run as dynamo user with UID/GID matched to your host user, which is useful when mounting partitions. It will also contain development tools.
./build.sh --framework vllm --target local-dev
# Build TensorRT-LLM development image called dynamo:latest-trtllm
...
...
@@ -256,7 +275,7 @@ The `run.sh` script launches Docker containers with the appropriate configuratio
**Key Features:**
-**GPU Management**: Automatic GPU detection and allocation
-**Volume Mounting**: Workspace and HuggingFace cache mounting
-**User Management**: Root or user-based container execution
-**User Management**: Non-root `dynamo` user execution (UID 1000, GID 0), with optional `--user` flag to override
Anant Sharma <anants@nvidia.com>