Ansible Role: Notarius

Installs and configures Notarius from source on Ubuntu 26.04 (x86_64 or aarch64). The role requires gathered facts and uses privilege escalation only for dependency installation and root-owned application state.

Variables

notarius_version: v0.8.1
notarius_repository_url: https://gitea.maximumdirect.net/eric/notarius.git
notarius_source_dir: /usr/local/src/notarius
notarius_binary_path: /usr/local/bin/notarius
notarius_manage_build_dependencies: true
notarius_go_snap_channel: 1.26/stable
notarius_go_binary: /snap/bin/go
notarius_config_path: /usr/local/etc/notarius/config.yml
notarius_config_owner: root
notarius_config_group: root
notarius_config_directory_mode: "0755"
notarius_config_file_mode: "0644"
notarius_config_version: 5
notarius_promptkit_profile_dir: null
notarius_promptkit_profile_file: null
notarius_promptkit_transient_retries: null
notarius_promptkit_local_backend_endpoint: null
notarius_promptkit_local_backend_concurrency_limit: null
notarius_configkit_imports: null
notarius_pipelines: null
notarius_concurrency_total_llm: null
notarius_concurrency_stage_workers_extract: null
notarius_output_directory: null
notarius_cache_chunk_plans_mode: null
notarius_cache_chunk_plans_directory: null
notarius_cache_checkpoints_enabled: null
notarius_cache_checkpoints_directory: null
notarius_debug_directory: null

When notarius_manage_build_dependencies is false, Git and the executable selected by notarius_go_binary must already be available. Otherwise, the role installs Git with APT and the classic Go Snap from notarius_go_snap_channel. It checks out notarius_version authoritatively, builds ./cmd/notarius directly to notarius_binary_path, and rebuilds only when that checkout changes or the binary is absent. The source tree is recursively owned by root:root; the binary is root:root mode 0755.

Configuration variables map directly to Notarius's versioned YAML fields. Every optional value defaults to null, so it and any empty parent section are omitted and Notarius retains ownership of its built-in defaults. The role always emits notarius_config_version as version. It manages notarius_config_path | dirname and the resulting file with notarius_config_owner, notarius_config_group, notarius_config_directory_mode, and notarius_config_file_mode. The standalone defaults are root:root, directory mode 0755, and file mode 0644; composing roles may override this generic configuration interface. notarius_pipelines is the native mapping supplied by the caller; the role does not merge or rewrite it. For example, inventory can compose fragments in the ordinary way:

notarius_pipelines: "{{ notarius_pipeline_group_one | combine(notarius_pipeline_group_two) }}"

notarius_configkit_imports is the complete native ConfigKit import list. It is caller-owned composition input: the role renders it into the root document but does not create or merge imported fragments. Relative import paths resolve from the managed root configuration directory.

PromptKit profile values identify profile sources or a local backend endpoint; they never contain credentials. Supply any credential environment variables outside this role.

notarius_promptkit_transient_retries renders promptkit.transient_retries when set. The null default omits it so Notarius retains its native retry behavior; integer 0 disables additional eligible transient transport attempts. These are additional attempts per generation for eligible transient provider failures, separate from pipeline and validator retries. Review combined retry and timeout budgets for a deployment rather than treating these settings as interchangeable. See the tagged v0.8.0 migration notes and v0.8.1 configuration reference.

Upgrading to v0.8.1

Notarius v0.8.0 replaced ConfigKit configuration selection via --config-profile and profiles/<name>.yml with --config-overlay and overlays/<name>.yml. Callers own their overlay files and application invocations; this role does not migrate files or select an overlay. The D&D suite's testing file and Narratio's downstream selector will be migrated together during coordinated suite integration, not by this standalone role.

Configuration overlays are distinct from PromptKit LLM profiles. notarius_promptkit_profile_dir and notarius_promptkit_profile_file still select LLM-profile sources, while pipeline llm_profile and --llm-profile still select an LLM profile. Those names and meanings are unchanged.

The v0.8.1 PromptKit dependency refresh changes profile-source checkpoint identity, so old checkpoints with the previous identity are not reused. Source-keyed chunk plans and published output are unaffected. Installing the role does not delete caches or force processing stages; see the tagged v0.8.1 release notes.

Example

- hosts: notarius_hosts
  roles:
    - role: ansible-role-notarius

Validation

The repository-local integration suite installs its pinned collection, runs syntax checking and production-profile lint, and exercises the default CLI and native configuration validation before requiring clean repeated convergence. It verifies an explicitly selected Notarius release, combines missing-binary recovery with a caller-supplied Go executable while dependency management is disabled, and checks null omission and explicit zero transport retries in rendered and effective configuration. A representative configuration also covers intentional falsey values, caller-side pipeline composition through a test-owned ConfigKit import, and native validation and inspection. It mutates only the managed source, binary, configuration, a test-owned imported fragment, and a private temporary directory, then restores the default deployment during cleanup.

tests/integration