Rigyard

Rigyard is a configuration-driven CLI for containerized robotics development. A single project manifest organizes layered image builds, development containers, project builds and tests inside containers, project-specific tasks, and multi-process debugging scenarios managed by tmux.

Features

• Build layered images from ordered Dockerfile fragments.
• Create reproducible development containers and run lifecycle hooks.
• Run project build scripts inside existing containers, starting stopped containers when allowed.
• Run user-defined test and test-result commands with the same configurable start behavior.
• Expose constrained project-specific container tasks through the CLI and interactive menu.
• Start tmux debugging scenarios in existing containers or Docker Compose services.
• Reuse configuration with global variables, string templates, and interactive runtime values.
• Use the same application behavior through direct commands or a branded one-shot interactive menu.

Requirements

• Linux and Bash for the setup script; it installs Python 3.12 and Rigyard using uv
• Docker for container operations; Compose scenarios require Docker Compose v2
• Scenario support requires tmux on the host and an interactive shell in each target container

Installation

Clone the repository, run the host setup, and activate the shared Rigyard environment:

git clone https://github.com/zz990099/Rigyard.git
cd Rigyard
bash scripts/bootstrap.sh
source scripts/activate.sh
rigyard --version

The script installs uv if needed and creates a Python environment without requiring Conda or a preinstalled Python. Source scripts/activate.sh in each new terminal. Docker, Compose, and tmux are checked but installed separately when needed. See installation and requirements for setup details, manual Conda installation, and troubleshooting. See the contribution guide for development checks.

For a CLI-only installation without a repository checkout, use uv tool install --python 3.12 rigyard. The Bash setup and activation scripts above belong to the checkout.

Quick start

By default, Rigyard reads rigyard.yaml from the current directory:

version: 3

metadata:
  name: robot-development

workspace:
  command_alias: robot

variables:
  PROJECT_ROOT: ${RIGYARD_ROOT}
  BRANDING_ROOT: ${PROJECT_ROOT}/branding
  CONTAINER_WORKSPACE_ROOT: /workspace

branding:
  logo_file: ${BRANDING_ROOT}/logo.txt

sources:
  images: [config/images.yaml]
  containers: [config/containers.yaml]
  builds: [config/builds.yaml]
  tests: [config/tests.yaml]
  tasks: [config/tasks.yaml]
  scenarios: [config/scenarios.yaml]

Validate the configuration and run configured operations:

rigyard validate
rigyard image build development
rigyard container create development
rigyard build native
rigyard test run unit
rigyard test report unit
rigyard task run clean
rigyard scene start robot-system development

Run rigyard without a subcommand to open the one-shot interactive menu:

rigyard

With the built-in logo and the example sources configured, the menu looks like this (colours omitted):

$ rigyard
██████╗ ██╗ ██████╗ ██╗   ██╗ █████╗ ██████╗ ██████╗
██╔══██╗██║██╔════╝ ╚██╗ ██╔╝██╔══██╗██╔══██╗██╔══██╗
██████╔╝██║██║  ███╗ ╚████╔╝ ███████║██████╔╝██║  ██║
██╔══██╗██║██║   ██║  ╚██╔╝  ██╔══██║██╔══██╗██║  ██║
██║  ██║██║╚██████╔╝   ██║   ██║  ██║██║  ██║██████╔╝
╚═╝  ╚═╝╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝

Project: robot-development
Configuration: /workspace/robot-development/rigyard.yaml

1) Build image
2) Create container
3) Build project
4) Scene…
5) Test…
6) Tasks…
0) Exit
Select [0-6]:

Custom terminal logos can be inline or loaded from a templated path; see the root manifest guide.

When the manifest lives elsewhere, pass it explicitly or bind the current workspace:

rigyard --config path/to/rigyard.yaml validate
rigyard init -f path/to/rigyard.yaml
robot build native

Configured aliases are installed in the active Conda or virtual environment. They are generic commands that discover the nearest current-or-parent workspace at runtime, so the same alias can be shared by multiple workspaces. They can be removed with rigyard alias remove.

Documentation

• Getting started
• Installation and requirements
• Configuration overview
• Global variables and string templates
• Runtime values
• Images
• Containers
• Project builds
• Tests
• Custom tasks
• Scenarios
• CLI reference
• Configuration schema reference
• Exit codes

Start with the minimal example or browse the complete robot-development reference project.

License

MIT

Powered by Codex — AI-assisted development and documentation.