rostainer

A flexible, distro agnostic tool for ROS (1 and 2) development using Docker containers.

Requires Docker and Python 3 on the host; target machines for rostainer package deployments need only Docker. On Python 3.11+ the CLI is standard-library only; on older Python (e.g. Ubuntu 22.04's default 3.10) pipx also installs the small tomli package, for reading .rostainer.toml.

Full documentation

This README only covers the quick start. Everything else - the full .rostainer.toml settings reference, GPU acceleration, hardware access, volume mounts, networking, packaging for deployment, LSP setup, and the rostainer_cli API reference - is in the documentation: https://bmillerklugman.pages.whoi.edu/rostainer/ (for the latest release).

It's built from docs/; to read it for your checkout instead, build and open it locally:

pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html
python3 -m http.server -d docs/_build/html   # then open http://localhost:8000

Quick Start

pipx install rostainer                  # or: uv tool install rostainer (see docs/)

mkdir my_ros_workspace && cd my_ros_workspace
rostainer init                          # scaffolds .rostainer.toml and src/
rostainer start                         # prompts for ROS distro/middleware
rostainer shell                         # drop into the running container

Commands

• rostainer init - Initialize a new ROS workspace with example configs
• rostainer start - Start ROS environment (prompts for distro/middleware)
• rostainer restart - Restart ROS environment, keeping its build (fast)
• rostainer rebuild - Rebuild the workspace from scratch (--image: the Docker image too)
• rostainer stop - Stop running ROS environment, for start to resume quickly (--rm: remove the container; the build is kept either way)
• rostainer shell - Drop into bash shell in running container
• rostainer logs - Show a running container's logs, or just its build errors
• rostainer status - Show status of ROS environment
• rostainer prune - Remove unused build caches, old images and old package bundles
• rostainer package - Build a deployable runtime image and install it on a target machine

Credits

This toolkit created with help from LLMs (Claude + Gemini)