Metadata-Version: 2.5
Name: rostainer
Version: 0.0.2
Summary: A flexible, distro agnostic tool for ROS (1 and 2) development using Docker containers
Project-URL: Homepage, https://git.whoi.edu/bmillerklugman/rostainer
Project-URL: Documentation, https://bmillerklugman.pages.whoi.edu/rostainer/
Author: rostainer contributors
License-Expression: MIT
License-File: LICENSE
Keywords: devcontainer,docker,robotics,ros,ros2
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Requires-Dist: tomli; python_version < '3.11'
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: shibuya; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Description-Content-Type: text/markdown

# rostainer

[![pipeline status](https://git.whoi.edu/bmillerklugman/rostainer/badges/main/pipeline.svg)](https://git.whoi.edu/bmillerklugman/rostainer/-/commits/main)
[![coverage report](https://git.whoi.edu/bmillerklugman/rostainer/badges/main/coverage.svg)](https://git.whoi.edu/bmillerklugman/rostainer/-/commits/main)
[![PyPI](https://img.shields.io/pypi/v/rostainer.svg)](https://pypi.org/project/rostainer/)
[![docs](https://img.shields.io/badge/docs-GitLab%20Pages-blue)](https://bmillerklugman.pages.whoi.edu/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:

```bash
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

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