131 lines
6.0 KiB
Markdown
131 lines
6.0 KiB
Markdown
# Ansible Role: Notarius
|
|
|
|
Installs and configures [Notarius](https://gitea.maximumdirect.net/eric/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
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.0/docs/releases/v0.8.0.md)
|
|
and [v0.8.1 configuration reference](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/config.md).
|
|
|
|
## 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](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/releases/v0.8.1.md).
|
|
|
|
## Example
|
|
|
|
```yaml
|
|
- 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.
|
|
|
|
```sh
|
|
tests/integration
|
|
```
|