How to Set Up Docker Deployment for DimOS Robotics Applications: Complete Guide

DimOS provides a layered Docker image architecture with a helper build script (bin/dockerbuild) to create reproducible ROS 2 environments for robotics deployment.

This guide walks you through the complete Docker deployment process for DimOS (dimensionalOS/dimos), an open-source robotics operating system. By containerizing the full ROS 2 stack alongside Python development tools, DimOS enables consistent deployment across robot platforms including Go2, G1, XArm, and aerial drones.

DimOS Docker Image Architecture

DimOS implements a three-tier image hierarchy designed for incremental complexity. Each layer extends the previous one, allowing you to choose exactly the environment depth your robotics application requires.

Base ROS Image (docker/ros/Dockerfile) provides the foundational Ubuntu 22.04 system with ROS 2 Humble (or Jazzy) pre-installed. This is the minimal viable image for pure ROS deployments.

Python-Enabled Image (docker/python/Dockerfile) extends the base with UV-managed Python tooling, pip, and additional system libraries. Use this when your robotics applications require specific Python dependencies beyond the ROS ecosystem.

Development Image (docker/dev/Dockerfile) combines both previous layers with debugging utilities and development conveniences. This "all-in-one" catch-all container serves as the standard development environment for active DimOS robotics work.

Building DimOS Docker Images

The repository includes bin/dockerbuild, a thin Bash wrapper that automates Docker build commands with correct contexts and tagging conventions. Rather than manually specifying Dockerfiles, you invoke the script with the target image name.

# Build the ROS base image

./bin/dockerbuild ros

# Output: ghcr.io/dimensionalos/ros:dev

# Build the Python-extended image

./bin/dockerbuild python

# Output: ghcr.io/dimensionalos/ros-python:dev

# Build the full development image

./bin/dockerbuild dev

# Output: ghcr.io/dimensionalos/ros-dev:dev

The script automatically selects the proper Dockerfile from the docker/ directory and applies the GitHub Container Registry naming convention. For CI/CD pipelines, these images push directly to ghcr.io/dimensionalos/ using the tags shown above.

Running DimOS Containers

After building, launch containers using standard Docker commands with specific flags for robotics hardware access. The DimOS documentation in docs/development/docker.md recommends host networking and volume mounting for live development.

# Interactive development shell

docker run -it --rm \
    --network host \
    --volume "$PWD":/workdir \
    ghcr.io/dimensionalos/ros-dev:dev \
    bash

The --network host flag grants direct access to host networking protocols required by LCM (Lightweight Communications and Marshalling) and ROS 2 discovery mechanisms. Mounting $PWD to /workdir enables live code editing without rebuilding the image.

Docker Compose for Complex Stacks

For multi-container robotics applications such as navigation stacks, DimOS provides Docker Compose configurations. The navigation example in docker/navigation/README.md demonstrates orchestrating hardware bridges and ROS nodes.

cd docker/navigation
ROS_DISTRO=humble docker compose -f docker-compose.yml up --build

Replace humble with jazzy when targeting the ROS 2 Jazzy distribution. This Compose file, located at docker/navigation/docker-compose.yml, handles inter-container communication and hardware device mounting automatically.

Summary

• Three-tier architecture: Base ROS (docker/ros/Dockerfile), Python-enabled (docker/python/Dockerfile), and full development (docker/dev/Dockerfile) images provide flexible environment selection.
• Automated builds: The bin/dockerbuild script eliminates manual Dockerfile path specification and enforces consistent tagging.
• Hardware access: Use --network host when running containers to enable LCM and ROS 2 communication with physical robots.
• Orchestration support: Complex applications utilize Docker Compose files in subdirectories like docker/navigation/ for multi-service deployment.

Frequently Asked Questions

What base operating system do DimOS Docker images use?

All DimOS Docker images build on Ubuntu 22.04 LTS. The base ROS image installs ROS 2 Humble Hawksbill (or Jazzy Jalisco on alternative branches), ensuring compatibility with standard robotics middleware while maintaining long-term support through 2027.

How do I add custom Python packages to a DimOS container?

Extend the existing image hierarchy by creating a new Dockerfile that uses ghcr.io/dimensionalos/ros-python:dev as its base image. Install additional packages using pip or uv (the included Python package manager), then rebuild using docker build. Alternatively, mount a requirements.txt file into the running container and install dependencies at runtime for development purposes.

Can I use these Docker images for production deployment on physical robots?

Yes. While the dev tag includes debugging tools, you can build production variants by modifying the Dockerfiles to remove development utilities. The bin/dockerbuild script supports custom tags, and the GitHub Container Registry integration allows versioning specific releases for fleet deployment across Go2, G1, XArm, and drone platforms.

Where is the complete Docker documentation located?

The comprehensive developer guide resides at docs/development/docker.md in the repository root. This file contains detailed instructions for installing Docker, configuring GitHub Container Registry authentication, setting up CI pipelines, and troubleshooting hardware access permissions for robotics applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}