eric/ansible-role-seriatim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simplify the Seriatim role

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-08 01:07:23 +00:00
parent 6fb1aa24cc
commit 325a5c7901
10 changed files with 200 additions and 916 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
README.md
View File

@@ -1,119 +1,49 @@
# Ansible Role: Seriatim
Installs the [Seriatim](https://gitea.maximumdirect.net/eric/seriatim)
transcript processor from source. The role supports Ubuntu 26.04 on `amd64`
and `arm64` hosts and is independently usable outside the D&D pipeline role.
The role manages its build dependencies and a root-owned source checkout,
builds a native static executable, validates it, and safely installs it.
Role source and issue tracking are hosted in the
[ansible-role-seriatim repository](https://gitea.maximumdirect.net/eric/ansible-role-seriatim)
and its [issue tracker](https://gitea.maximumdirect.net/eric/ansible-role-seriatim/issues).
## Requirements
Ansible Core 2.18 or newer is required. Install the pinned collection
dependency before using or validating the role:
```sh
ansible-galaxy collection install -r collections/requirements.yml
```
The consuming play must set `become: true` or provide equivalent root
privileges. The role manages system packages, classic snaps, root-owned source
and state directories, and the installed executable under `/usr/local` by
default.
Installs [Seriatim](https://gitea.maximumdirect.net/eric/seriatim) from source
on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered facts and
privilege escalation for its default paths and dependency installation.
## Variables
| Variable | Default | Description |
| --- | --- | --- |
| `seriatim_version` | `v1.5.0` | Release identity expected from the installed binary. |
| `seriatim_repository_url` | `https://gitea.maximumdirect.net/eric/seriatim.git` | Source repository URL. |
| `seriatim_source_ref` | `{{ seriatim_version }}` | Git tag, branch, or commit to check out. |
| `seriatim_build_version` | `{{ seriatim_version }}` | Version injected into build metadata. |
| `seriatim_source_dir` | `/usr/local/src/seriatim` | Fully managed source checkout. |
| `seriatim_binary_path` | `/usr/local/bin/seriatim` | Installed executable path. |
| `seriatim_build_state_dir` | `/usr/local/src/seriatim.ansible-build-state` | Sidecar directory for build inputs and output state. |
| `seriatim_manage_build_dependencies` | `true` | Install Git and Go when enabled. |
| `seriatim_go_snap_channel` | `1.26/stable` | Go Snap channel. |
| `seriatim_go_binary` | `/snap/bin/go` | Go executable used to inspect and build. |
| `seriatim_go_build_flags` | `[-trimpath]` | Ordered Go build arguments before `-ldflags`. |
| `seriatim_go_ldflags` | `-s -w -X gitea.maximumdirect.net/eric/seriatim/internal/buildinfo.Version={{ seriatim_build_version }}` | Linker flags passed as one argument. |
| `seriatim_go_package` | `./cmd/seriatim` | Go package built from the checkout. |
```yaml
seriatim_version: v1.5.0
seriatim_repository_url: https://gitea.maximumdirect.net/eric/seriatim.git
seriatim_source_dir: /usr/local/src/seriatim
seriatim_binary_path: /usr/local/bin/seriatim
seriatim_manage_build_dependencies: true
seriatim_go_snap_channel: 1.26/stable
```
For development revisions, set both `seriatim_source_ref` and an honest
`seriatim_build_version`. Released deployments should select immutable tags.
When `seriatim_manage_build_dependencies` is `false`, Git and `/snap/bin/go`
must already be available. Otherwise, the role installs Git with APT and the
classic Go Snap from `seriatim_go_snap_channel`.
When `seriatim_manage_build_dependencies` is enabled, the role installs Git
and converges the classic Go Snap to `seriatim_go_snap_channel`. When disabled,
both Git and the configured Go executable must already be available, and Go
must be version 1.25 or newer.
The checkout is authoritative: local source changes are discarded while
selecting `seriatim_version`. The role builds `./cmd/seriatim` directly to
`seriatim_binary_path` using `/snap/bin/go`, `CGO_ENABLED=0`, `GOWORK=off`,
`GOTOOLCHAIN=local`, `-trimpath`, and release linker metadata. It rebuilds when
the checkout changes, the binary is absent, or `seriatim --version` does not
exactly match the selected version.
The checkout is authoritative: tracked changes and all untracked or ignored
files beneath `seriatim_source_dir` are discarded during convergence. The
repository URL may point to a private remote, but authentication must be
provided independently through the managed host's Git configuration or SSH
environment; this role does not manage credentials or accept unknown host
keys.
The source tree is recursively owned by `root:root`. The installed binary is a
regular file owned by `root:root` with mode `0755`.
## Build and installation behavior
Builds run from the selected checkout with `GOWORK=off`,
`GOTOOLCHAIN=local`, `CGO_ENABLED=0`, the configured ordered build flags, and
the upstream version-injection linker flags. The resulting executable is
staged and must report the exact configured version before it atomically
replaces `seriatim_binary_path`. It is installed as `root:root` mode `0755`.
The role records readable inputs, their SHA-256 fingerprint, and the installed
binary checksum beneath `seriatim_build_state_dir`. A source commit, compiler
identity, Go path, version, flags, linker flags, package, or fixed environment
change triggers a rebuild. Missing or corrupt state, a modified binary, or an
incorrect installed version also triggers rebuilding. Failed compilation or
staged validation leaves the previous installed binary and successful state
untouched.
For example, development from a branch must identify both source and output:
## Example
```yaml
seriatim_source_ref: feature/example
seriatim_build_version: v1.5.0-dev
- hosts: seriatim_hosts
become: true
roles:
- role: ansible-role-seriatim
```
## Static validation
## Validation
```sh
ANSIBLE_COLLECTIONS_PATH="$PWD/.ansible/collections" \
../.venv/bin/ansible-playbook -i tests/inventory tests/converge.yml \
--syntax-check
ANSIBLE_COLLECTIONS_PATH="$PWD/.ansible/collections" \
../.venv/bin/ansible-lint .
```
## Development and integration validation
Create the workspace virtual environment described by the control repository
and run the complete local suite from this repository with:
The integration driver installs pinned collection dependencies, runs syntax
checking and ansible-lint, converges and verifies the default release, then
requires an immediate repeat with `changed=0` and `failed=0`:
```sh
tests/integration
```
The driver installs the pinned collection into the ignored local `.ansible`
directory, runs static checks, and then mutates the local host using privilege
escalation. It manages `/usr/local/src/seriatim`,
`/usr/local/src/seriatim.ansible-build-state`, and
`/usr/local/bin/seriatim`; do not run it where those paths contain data that
must be preserved. It verifies convergence, idempotence, platform guards,
authoritative source cleanup, compiler-version invalidation, and preservation
of a working installation after a failed build.
The driver uses temporary Go wrappers and removes them on exit. It attempts to
restore the default role state after a failure. Recovery consists only of
rerunning `tests/integration` or the default `tests/converge.yml`; no manual
deletion of managed paths is required.
## License
BSD-3-Clause