# How to Set Up Docker Deployment for DimOS Robotics Applications: Complete Guide > Discover how to set up Docker deployment for DimOS robotics applications. Follow our guide to create reproducible ROS 2 environments using a layered Docker image architecture and helper build script. - Repository: [Dimensional/dimos](https://github.com/dimensionalOS/dimos) - Tags: how-to-guide - Published: 2026-03-15 --- **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. ```bash # 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`](https://github.com/dimensionalOS/dimos/blob/main/docs/development/docker.md) recommends host networking and volume mounting for live development. ```bash # 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`](https://github.com/dimensionalOS/dimos/blob/main/docker/navigation/README.md) demonstrates orchestrating hardware bridges and ROS nodes. ```bash 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`](https://github.com/dimensionalOS/dimos/blob/main/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`](https://github.com/dimensionalOS/dimos/blob/main/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`](https://github.com/dimensionalOS/dimos/blob/main/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.