240 lines
11 KiB
Markdown
240 lines
11 KiB
Markdown
# Ansible Role: Narratio
|
|
|
|
Installs and configures [Narratio](https://gitea.maximumdirect.net/eric/narratio)
|
|
from source on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered
|
|
facts and uses task-level privilege escalation for dependencies and managed
|
|
application state.
|
|
|
|
## Variables
|
|
|
|
```yaml
|
|
narratio_version: v3.1.0
|
|
narratio_repository_url: https://gitea.maximumdirect.net/eric/narratio.git
|
|
narratio_source_dir: /usr/local/src/narratio
|
|
narratio_binary_path: /usr/local/bin/narratio
|
|
narratio_manage_build_dependencies: true
|
|
narratio_go_snap_channel: 1.26/stable
|
|
narratio_go_binary: /snap/bin/go
|
|
narratio_user: narratio
|
|
narratio_group: narratio
|
|
narratio_config_path: /usr/local/etc/narratio/pipeline.yml
|
|
narratio_config_owner: root
|
|
narratio_config_group: narratio
|
|
narratio_config_directory_mode: "0750"
|
|
narratio_config_file_mode: "0640"
|
|
narratio_workspace_root: /var/lib/narratio
|
|
narratio_campaigns_root: /usr/local/share/narratio/campaigns
|
|
narratio_spool_root: /var/spool/narratio
|
|
narratio_cache_root: /var/cache/narratio
|
|
```
|
|
|
|
`narratio_whisperx_transcribe_url` is required and must be an absolute HTTP or
|
|
HTTPS URL. Every other pipeline setting is optional and defaults to `null`:
|
|
|
|
```yaml
|
|
narratio_configkit_imports: null
|
|
narratio_workspace_cleanup_after_publish: null
|
|
narratio_campaigns_default_campaign_id: null
|
|
narratio_storage_backend: null
|
|
narratio_storage_s3_bucket: null
|
|
narratio_storage_s3_root_prefix: null
|
|
narratio_storage_s3_region: null
|
|
narratio_storage_s3_endpoint: null
|
|
narratio_storage_s3_force_path_style: null
|
|
narratio_storage_s3_access_key_id: null
|
|
narratio_storage_s3_secret_access_key: null
|
|
narratio_spool_delete_audio_after_publish: null
|
|
narratio_cache_s3_audio: null
|
|
narratio_publish_enabled: null
|
|
narratio_publish_upload_run: null
|
|
narratio_publish_outputs: null
|
|
narratio_whisperx_language: null
|
|
narratio_whisperx_timeout: null
|
|
narratio_whisperx_retries: null
|
|
narratio_whisperx_retry_delay: null
|
|
narratio_whisperx_concurrency: null
|
|
narratio_seriatim_binary: null
|
|
narratio_seriatim_timeout: null
|
|
narratio_seriatim_output_schema: null
|
|
narratio_seriatim_coalesce_gap: null
|
|
narratio_seriatim_report: null
|
|
narratio_seriatim_env_overlap_word_run_gap: null
|
|
narratio_seriatim_env_overlap_word_run_reorder_window: null
|
|
narratio_seriatim_env_backchannel_max_duration: null
|
|
narratio_seriatim_env_filler_max_duration: null
|
|
narratio_audita_binary: null
|
|
narratio_audita_timeout: null
|
|
narratio_audita_credentials: null
|
|
narratio_audita_modules: null
|
|
narratio_audita_overlay: null
|
|
narratio_audita_proposal_profile: null
|
|
narratio_audita_validation_profile: null
|
|
narratio_audita_transcript_description: null
|
|
narratio_audita_config_path: null
|
|
narratio_audita_output_schema: null
|
|
narratio_normalize_output_path: null
|
|
narratio_normalize_output_schema: null
|
|
narratio_normalize_report: null
|
|
narratio_trim_enabled: null
|
|
narratio_trim_output_path: null
|
|
narratio_trim_bounds_prompt_id: null
|
|
narratio_trim_bounds_profile_id: null
|
|
narratio_trim_bounds_transcript_input_name: null
|
|
narratio_trim_bounds_output_path: null
|
|
narratio_trim_bounds_timeout: null
|
|
narratio_trim_bounds_render_debug: null
|
|
narratio_trim_bounds_render_output_path: null
|
|
narratio_trim_seriatim_report: null
|
|
narratio_render_enabled: null
|
|
narratio_render_format: null
|
|
narratio_render_title: null
|
|
narratio_render_include_timestamps: null
|
|
narratio_render_include_segment_ids: null
|
|
narratio_render_include_metadata: null
|
|
narratio_scriptorium_binary: null
|
|
narratio_scriptorium_credentials: null
|
|
narratio_scriptorium_config_path: null
|
|
narratio_scriptorium_timeout: null
|
|
narratio_scriptorium_render_debug: null
|
|
narratio_scriptorium_artifacts: null
|
|
narratio_scriptorium_artifact_families: null
|
|
narratio_notarius_enabled: null
|
|
narratio_notarius_binary: null
|
|
narratio_notarius_config_path: null
|
|
narratio_notarius_config_overlay: null
|
|
narratio_notarius_pipeline_id: null
|
|
narratio_notarius_timeout: null
|
|
narratio_notarius_working_directory: null
|
|
narratio_notarius_credentials: null
|
|
narratio_notarius_resume: null
|
|
narratio_notarius_chunk_cache: null
|
|
narratio_notarius_references: null
|
|
narratio_notarius_outputs: null
|
|
narratio_notification_mode: null
|
|
```
|
|
|
|
With dependency management enabled, the role installs Git and the classic Go
|
|
Snap from `narratio_go_snap_channel`. When disabled, Git and the executable at
|
|
`narratio_go_binary` must already be available. The role checks out
|
|
`narratio_version`, builds `./cmd/narratio` to `narratio_binary_path`, and
|
|
rebuilds only when the checkout changes or the binary is absent.
|
|
|
|
The `narratio` account owns the workspace, spool, and cache roots, which are
|
|
group-writable setgid directories. The campaign registry is `root:narratio`
|
|
and operator-readable; its content remains caller-managed. Configuration
|
|
ownership and modes are independently configurable: the standalone defaults
|
|
are `root:narratio`, mode `0750` for the directory and `0640` for the managed
|
|
pipeline file. Composing roles may override these inputs without changing the
|
|
writable-root policy.
|
|
|
|
Null pipeline values and their empty parent mappings are omitted; non-null
|
|
falsey values are preserved. `narratio_publish_outputs`,
|
|
`narratio_notarius_references`, `narratio_notarius_outputs`,
|
|
`narratio_scriptorium_artifacts`, and `narratio_scriptorium_artifact_families`
|
|
are complete native caller values, so callers may compose them before assigning
|
|
them and the role does not merge or rewrite them. The optional
|
|
`narratio_notarius_config_overlay` selects a Notarius ConfigKit overlay without
|
|
coupling it to Narratio's own overlay name. The optional `narratio_notarius_resume`
|
|
and `narratio_notarius_chunk_cache` settings expose Narratio's native extraction
|
|
and chunk-plan choices; this generic role assigns no D&D-specific credential or
|
|
cache policy.
|
|
ConfigKit imports and selected overlays are externally managed, and this role
|
|
does not install the downstream applications, campaign content, or suite policy.
|
|
|
|
## Upgrading from Narratio v2
|
|
|
|
Narratio v3 removes these role variables and their native fields:
|
|
`narratio_audita_llm_api_key`, `narratio_audita_base_url`,
|
|
`narratio_audita_model`, `narratio_audita_total_llm_concurrency`,
|
|
`narratio_audita_proposal_llm_concurrency`,
|
|
`narratio_audita_validation_model`,
|
|
`narratio_audita_validation_llm_concurrency`,
|
|
`narratio_audita_work_dir_retention`, and `narratio_audita_report`.
|
|
Replace `narratio_notarius_llm_api_key` with the list-valued
|
|
`narratio_notarius_credentials`; rename `narratio_notarius_config_profile` to
|
|
`narratio_notarius_config_overlay`. Existing deployments that cannot migrate
|
|
these inputs should retain their previous role pin. See the tagged
|
|
[v3.0.0 release notes](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/releases/v3.0.0.md).
|
|
|
|
`narratio_audita_credentials` and `narratio_notarius_credentials` are lists of
|
|
environment-variable or secret-reference **names**, never credential values.
|
|
Callers supply nonempty values through Narratio's run environment or supported
|
|
secret source. Narratio resolves configured names when loading a pipeline,
|
|
including when the downstream stage will be skipped. Audita v2 needs names for
|
|
every credential in its configured backends, even backends not selected by the
|
|
current profiles; Notarius names must match its selected provider profiles.
|
|
The role does not inspect downstream files or resolve secrets. Null omits a
|
|
list or selector, `[]` emits an explicit empty list, and `""` emits an explicit
|
|
empty selector. A Narratio overlay replaces a credential list rather than
|
|
appending to it.
|
|
|
|
`narratio_scriptorium_credentials` is likewise an optional list of exact
|
|
environment-variable or secret-reference names, not credential values. Null
|
|
omits the field; `[]` writes an explicit empty list and forwards nothing.
|
|
When nonempty, Narratio resolves every selected name to a nonempty value at
|
|
pipeline load time, even for inspection commands that do not run Scriptorium.
|
|
Provision those values through Narratio's existing process environment or
|
|
secrets-directory mechanism. Provider/profile selection remains Scriptorium's
|
|
responsibility, and this standalone role does not choose provider names.
|
|
|
|
Audita v2 owns its configuration, backend/model definitions, PromptKit profiles,
|
|
reporting, and debug policy. Configure it independently before using polish;
|
|
the role does not generate downstream files or guess replacements for the
|
|
removed tuning fields. The Audita overlay, proposal profile, and validation
|
|
profile selectors are independent of each other and Narratio's selected
|
|
overlay. The Notarius `config_overlay` selector is likewise independent; null
|
|
adds no downstream selection, while empty, `default`, and named strings are
|
|
passed to Notarius unchanged. Selected downstream features require compatible
|
|
Audita and Notarius executables; this role adds no version gate. See the tagged
|
|
[Audita](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/audita.md)
|
|
and [Notarius](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/notarius.md)
|
|
integration contracts.
|
|
|
|
For Narratio itself, replace `--profile` with `--overlay` and move selected
|
|
`profiles/<name>.yml` files to `overlays/<name>.yml` beside the pipeline root.
|
|
Explicit ConfigKit imports from a directory named `profiles` remain valid;
|
|
PromptKit LLM-profile files are a separate concept. Notarius's renamed
|
|
`config_overlay` selects its own `overlays/` files, replacing its retired
|
|
configuration-profile selection. The D&D suite's testing file and selector
|
|
migrate later with coordinated suite integration, not in this generic role.
|
|
|
|
Before opening an affected existing session, follow the tagged
|
|
[manifest migration procedure](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/operations.md#migrating-manifest-overlay-provenance):
|
|
back up the local manifest and change only
|
|
`effective_config.selected_profile` to `selected_overlay` (or remove the
|
|
retired informational member), preserving local progress and checkpoints.
|
|
Immutable remote snapshots are not edited in place. For named Notarius
|
|
selectors, the renamed field changes extraction resume evidence: the next
|
|
applicable run regenerates extraction with normal dependent invalidation.
|
|
Omitted/base selection does not gain invalidation solely from the rename.
|
|
The role performs no manifest migration, cache cleanup, or blanket forced
|
|
reruns.
|
|
|
|
## Example
|
|
|
|
```yaml
|
|
- hosts: narratio_hosts
|
|
roles:
|
|
- role: ansible-role-narratio
|
|
vars:
|
|
narratio_whisperx_transcribe_url: https://whisperx.example.test/transcribe
|
|
```
|
|
|
|
## Validation
|
|
|
|
The repository-local integration suite installs its pinned collection and runs
|
|
syntax checking and production-profile lint. It validates a baseline managed
|
|
pipeline through Narratio as its application account and requires immediate
|
|
clean repeated convergence. It explicitly selects `v2.1.0` and checks native
|
|
version output, then combines missing-binary recovery with a caller-supplied Go
|
|
executable while dependency management is disabled. A representative pipeline
|
|
checks null omission, falsey values, caller-composed native collections,
|
|
credential-name lists, downstream selectors, and the native Notarius `resume`
|
|
and chunk-cache fields. It validates named and explicit-empty configurations
|
|
offline and requires clean repeats. The suite restores the baseline deployment
|
|
during cleanup.
|
|
|
|
```sh
|
|
tests/integration
|
|
```
|