voraus IPC Tools Ansible

CI black isort

voraus IPC related Ansible roles and tools. This collection helps to set up a real-time system with all prerequisites to deploy the voraus.core.

[!NOTE] This collection and its roles are tested against Debian 13 (trixie), and might need modifications for other systems.


Prerequisites

  • An IPC running debian

  • SSH root access to this IPC

Quickstart

  1. Install ansible and the collection. This pulls in the ansible.posix and community.general collections that this collection depends on.

uv tool install ansible-core

ansible-galaxy collection install voraus.ipc_tools

  1. Copy the example inventory to a inventory.yml file and change it according to your needs. In this example, we assume that the IPC is reachable via the IP address 192.168.1.1.

  2. Run the example playbook shipped with the collection.

ansible-playbook voraus.ipc_tools.example -i inventory.yml

Documentation

Please refer to the official documentation.


Development

This project is managed with uv. The following creates .venv, installs the Python version pinned in .python-version and installs the exact dependency versions recorded in uv.lock:

uv sync --locked --all-extras
source .venv/bin/activate

All checks run through tox. Each tox environment is installed from uv.lock as well, so local runs and CI use identical package versions.

Command

Purpose

tox -e lint

ansible-lint, prettier, isort, black, mypy, ruff, pylint and doc8

tox -e docs

Run the doctests and build the Sphinx docs into docs/build/html

tox -e build

Build the collection tarball

tox -e test

Run the molecule test suite, see below

Without activating the environment, prefix the commands with uv run --all-extras, for example uv run --all-extras tox -e lint.

After changing a dependency in pyproject.toml, refresh the lockfile and commit the result. CI installs with --locked and fails on a stale uv.lock:

uv lock

Molecule tests

tox -e test is intended for local use only. CI runs molecule per role in test.yml, because every scenario boots a virtual machine and needs root privileges on the runner. Locally, vagrant and libvirt have to be available on the host.

# Run every scenario
tox -e test

# Run a single scenario
tox -e test -- test -s grub_config

Releasing

Releases are cut by release-please. It keeps a release pull request open that collects every Conventional Commit merged into main, and derives the next version from those commit types. Merging that pull request is the release:

  1. CHANGELOG.md, voraus/ipc_tools/galaxy.yml, pyproject.toml and uv.lock are bumped to the same version.

  2. The X.Y.Z tag and the GitHub release are created.

  3. The tag triggers pipeline.yml, which publishes the collection to Ansible Galaxy and the docs to GitHub Pages.

Nothing is tagged or published by hand, so the only thing that decides the next version is the commit history. The sections of the changelog are configured in release-please-config.json.


Getting Started

Roles

The collection currently contains the following roles, please refer to their individual documentation for more details:

Changelog

License Compliance Information