ros2docker 0.1.2

Versioned CLI and Python API for building and running ROS 2 Docker workspaces.

ros2docker

ros2docker is a versioned Python CLI and API for building and running ROS 2 Docker workspaces from JSON-with-comments config files.

Install

Stable release:

pipx install ros2docker

Latest development version:

pipx install --force git+https://github.com/develNor/ros2docker.git@main

Non-pipx fallback:

python3 -m pip install --user ros2docker

Development Install

When developing ros2docker, install this checkout in editable mode so the host ros2docker command imports the local source:

pipx install --force --editable /path/to/ros2docker

Normal Python source changes are picked up immediately by new ros2docker commands. Reinstall after changing package metadata, dependencies, or console entry points in pyproject.toml.

Verify the editable command with:

ros2docker run --no-build --dry-run -m .

The dry run should print a docker run command that mounts the current directory as /ws and starts bash, without requiring -f/--config.

CLI

ros2docker run -m /host/project
ros2docker run --no-build -m /host/project
ros2docker build -f ros2docker.json
ros2docker run -f ros2docker.json
ros2docker run -f ros2docker.json --no-build -- -v /host/data:/data
ros2docker stop -f ros2docker.json
ros2docker exec -f ros2docker.json -- bash -lc 'ros2 --help'
ros2docker validate -f ros2docker.json
ros2docker validate -f ros2docker.json --print-resolved
ros2docker doctor -f ros2docker.json
ros2docker --version
python -m ros2docker --version

Every Docker action accepts --dry-run, which prints the Docker argv and exits without running Docker. The -f/--config option is optional; without it, ros2docker uses the default config, which starts an interactive Bash shell. Use ros2docker exec to run a command inside an already-running container, such as one started with run_type: "up". validate checks config syntax and schema without Docker side effects. doctor reports host readiness diagnostics before a build or run.

Config

Config files are JSON with // and /* ... */ comments. Supported keys include:

{
  "container_name": "example_ros2container",
  "image_name": "ros2docker",
  "run_type": "bash",
  "tty": true,
  "stdin_open": true,
  "mount_ws": true,
  "enable_gui_forwarding": false,
  "forward_ssh_agent": false,
  "run_args": [],
  "extra_run_args": [],
  "build_args": {},
  "bake_ros_packages": [],
  "catmux_file": "/ws/catmux.yaml",
  "catmux_params": {},
  "command": "ros2 topic list"
}

The machine-readable schema lives at src/ros2docker/resources/schema/ros2docker.schema.json. See docs/configuration.md for the full configuration contract. Unknown top-level config keys are rejected.

Supported run_type values are:

• bash: start an interactive shell.
• command: run the configured command as a one-shot container.
• catmux: start a catmux session from catmux_file.
• up: start a detached, long-lived keepalive container for later exec commands.

tty and stdin_open control Docker run interactivity. When omitted, bash and catmux default both to true; command and up default both to false. Set them explicitly for an interactive command run.

mount_ws mounts the config-adjacent ws directory into /ws; normal project configs do not need to duplicate that mount in run_args.

Host paths in -v/--volume and bind --mount args expand ~ and environment variables. Relative ./ and ../ host paths are resolved from the config file directory.

bake_ros_packages paths are also resolved from the config file directory and copied into a temporary Docker build context. The installed Python package directory is never mutated during builds.

enable_gui_forwarding forwards the X11 socket at /tmp/.X11-unix. forward_ssh_agent forwards the host SSH_AUTH_SOCK path when the variable is set and points to an existing socket or file.

Security / Trust Boundary

ros2docker is intended for trusted developer workspaces, configs, and ROS packages. It can mount host paths, forward X11, forward the SSH agent, build arbitrary packages, and execute Docker containers. Treat project configs and workspace contents as code that can affect the host through those features, and do not run untrusted inputs with this tool.

Development

For contributor setup, local checks, PR modes, merge policy, and release workflow, see CONTRIBUTING.md. CI behavior is summarized in docs/ci.md, release publishing is summarized in docs/release.md, issue-driven work tracking is summarized in docs/work-items.md, and reusable task recipes live in .github/ISSUE_TEMPLATE/.

Python API

from ros2docker.api import build, run, build_run, stop, exec_shell
from ros2docker.config import load_config, get_config_dir
from ros2docker.commands import make_build_command, make_run_command