Metadata-Version: 2.5
Name: rostainer
Version: 0.0.4
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.7
Requires-Dist: importlib-metadata>=3.6; python_version < '3.10'
Requires-Dist: pydantic<3,>=2.5
Requires-Dist: tomli; python_version < '3.11'
Requires-Dist: typing-extensions>=4.6
Provides-Extra: deploy
Requires-Dist: rostainer-deploy; extra == 'deploy'
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: shibuya; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: instances
Requires-Dist: rostainer-instances; extra == 'instances'
Provides-Extra: package
Requires-Dist: rostainer-package; extra == 'package'
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.7+ on the host; target machines for
`rostainer package` deployments need only Docker. pipx installs the few
Python packages it uses (pydantic, to check `.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; `--workspace`: only the build, keeping installed
  dependencies, so it works offline)
- **`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 scratch`** - Open a throwaway ROS container, no workspace needed
- **`rostainer prune`** - Remove unused build caches, old images, and what
  plugins leave behind (e.g. old package bundles)

Features only some workspaces need are [plugins](https://bmillerklugman.pages.whoi.edu/rostainer/plugins/index.html),
installed next to rostainer (`pipx inject rostainer <plugin>`):

- **`rostainer package`** (`rostainer-package`) - Build a deployable runtime
  image and install it on a target machine
- **`rostainer instances`** (`rostainer-instances`) - Run copies of an
  environment, for simulation and tests

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