> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimensionalos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

# Docker Images

Dimos uses parallel Docker image hierarchies for ROS and non-ROS builds, allowing you to choose the environment that fits your use case.

## Image Hierarchy

<details>
  <summary>Pikchr</summary>

  ```pikchr fold output=assets/docker-hierarchy.svg theme={null}
  color = white
  fill = none

  # Base images
  U1: box "ubuntu:22.04" rad 5px fit wid 170% ht 170%
  U2: box "ubuntu:22.04" rad 5px fit wid 170% ht 170% at (U1.x + 2.5in, U1.y)

  # Labels
  text "Non-ROS Track" at (U1.x, U1.y + 0.5in)
  text "ROS Track" at (U2.x, U2.y + 0.5in)

  # Non-ROS track
  arrow from U1.s down 0.4in
  P: box "python" rad 5px fit wid 170% ht 170%
  arrow from P.s down 0.4in
  D: box "dev" rad 5px fit wid 170% ht 170%

  # ROS track
  arrow from U2.s down 0.4in
  R: box "ros" rad 5px fit wid 170% ht 170%
  arrow from R.s down 0.4in
  RP: box "ros-python" rad 5px fit wid 170% ht 170%
  arrow from RP.s down 0.4in
  RD: box "ros-dev" rad 5px fit wid 170% ht 170%

  # Cross-reference: same dockerfiles reused
  line dashed from P.e right 0.3in then down until even with RP then right to RP.w
  line dashed from D.e right 0.3in then down until even with RD then right to RD.w
  text "same dockerfiles" at (D.e.x + 1.2in, D.e.y + 0.4in)
  ```
</details>

<img src="https://mintcdn.com/dimensional/yosSz5_lMPgkJsO4/development/assets/docker-hierarchy.svg?fit=max&auto=format&n=yosSz5_lMPgkJsO4&q=85&s=4347042de48cf88eaea5a38227cec12b" alt="output" width="575" height="444" data-path="development/assets/docker-hierarchy.svg" />

## Images

All images are published to `ghcr.io/dimensionalos/`.

| Image        | Base         | Purpose                                            |
| ------------ | ------------ | -------------------------------------------------- |
| `python`     | ubuntu:22.04 | Core dimos with Python dependencies, no ROS        |
| `dev`        | python       | Development environment (editors, git, pre-commit) |
| `ros`        | ubuntu:22.04 | ROS2 Humble with navigation packages               |
| `ros-python` | ros          | ROS + dimos Python dependencies                    |
| `ros-dev`    | ros-python   | Full ROS development environment                   |

## Tags

Images are tagged based on the git branch:

| Branch           | Tag                                             |
| ---------------- | ----------------------------------------------- |
| `main`           | `latest`                                        |
| `dev`            | `dev`                                           |
| feature branches | sanitized branch name (e.g., `feature_foo_bar`) |

## When to Use Each Image

### Non-ROS Track (`python` → `dev`)

```sh skip theme={null}
docker run -it ghcr.io/dimensionalos/dev:latest bash
```

### ROS Track (`ros` → `ros-python` → `ros-dev`)

Use when you need ROS2 integration:

* Robot hardware control via ROS topics
* Navigation stack integration
* ROS message passing between components
* Running ROS tests (`pytest -m ros`)

```sh skip theme={null}
docker run -it ghcr.io/dimensionalos/ros-dev:latest bash
```

## Local Development

### Building Images Locally

Use the helper script:

```sh skip theme={null}
./bin/dockerbuild python    # Build python image
./bin/dockerbuild dev       # Build dev image
./bin/dockerbuild ros       # Build ros image
```

## CI/CD Pipeline

Images are built by [`.github/workflows/docker-build.yml`](/.github/workflows/docker-build.yml#L4) on merges to `main`/`dev` (when Docker files change) and weekly for base image security patches.

Tests and type checking run in [`.github/workflows/ci.yml`](/.github/workflows/ci.yml) using pre-built images.

### Build Trigger Paths

| Image    | Triggers on changes to             |
| -------- | ---------------------------------- |
| `ros`    | `docker/ros/**`, workflow files    |
| `python` | `docker/python/**`, workflow files |
| `dev`    | `docker/dev/**`                    |

## Dockerfile Structure

### Common Patterns

All Dockerfiles accept a `FROM_IMAGE` build arg for flexibility:

```dockerfile skip theme={null}
ARG FROM_IMAGE=ubuntu:22.04
FROM ${FROM_IMAGE}
```

This allows the same Dockerfile (e.g., `python`) to build on different bases.

### Python Package Installation

Images use [uv](https://github.com/astral-sh/uv) for fast dependency installation:

```dockerfile skip theme={null}
ENV UV_SYSTEM_PYTHON=1
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
RUN uv pip install '.[misc,cpu,sim,drone,unitree,web,perception,visualization]'
```

### Dev Image Features

The dev image ([`docker/dev/Dockerfile`](/docker/dev/Dockerfile)) adds:

* Git, git-lfs, pre-commit
* Editors (nano, vim)
* tmux with custom config
* Node.js (via nvm)
* Custom bash prompt with version info
* Entrypoint script that sources ROS setup