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

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)

skip

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)

skip

docker run -it ghcr.io/dimensionalos/ros-dev:latest bash

Local Development

Building Images Locally

Use the helper script:

skip

./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 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 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:

skip

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 for fast dependency installation:

skip

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) 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