ansible-role-narratio/README.md

Ansible Role: Narratio

Installs and configures 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

narratio_version: v3.0.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:

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_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. Credential lists contain environment-variable names only; credential values remain outside this role and are the caller's responsibility. 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.

Narratio v3 removes the old Audita tuning, report, retention, and singular-key role variables. It also replaces narratio_notarius_llm_api_key with narratio_notarius_credentials and renames narratio_notarius_config_profile to narratio_notarius_config_overlay. Existing deployments that cannot migrate these inputs should retain their previous Narratio role pin.

Example

- 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, and the native Notarius credential-reference, resume, and chunk-cache fields before native validation and a clean repeat. The suite restores the baseline deployment during cleanup.

tests/integration