Ansible Role: Scriptorium

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

scriptorium_version: v0.13.0
scriptorium_repository_url: https://gitea.maximumdirect.net/eric/scriptorium.git
scriptorium_source_dir: /usr/local/src/scriptorium
scriptorium_binary_path: /usr/local/bin/scriptorium
scriptorium_manage_build_dependencies: true
scriptorium_go_snap_channel: 1.26/stable
scriptorium_go_binary: /snap/bin/go
scriptorium_config_path: /usr/local/etc/scriptorium/config.yml
scriptorium_config_owner: root
scriptorium_config_group: root
scriptorium_config_directory_mode: "0755"
scriptorium_config_file_mode: "0644"
scriptorium_prompt_dir: null
scriptorium_profile_dir: null
scriptorium_schema_dir: null
scriptorium_server_addr: null
scriptorium_server_artifact_root: null
scriptorium_server_max_request_bytes: null
scriptorium_server_max_artifact_bytes: null
scriptorium_server_max_response_bytes: null
scriptorium_defaults_render_format: null
scriptorium_backends: null

When scriptorium_manage_build_dependencies is false, Git and the executable selected by scriptorium_go_binary must already be available. Otherwise, the role installs Git with APT and the classic Go Snap from scriptorium_go_snap_channel. It checks out scriptorium_version authoritatively, builds ./cmd/scriptorium directly to scriptorium_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.

Every application configuration variable defaults to null, so it and any empty parent section are omitted and Scriptorium retains ownership of its built-in defaults. When no values are selected, the role writes {} to scriptorium_config_path. It manages that file and its parent directory with scriptorium_config_owner, scriptorium_config_group, scriptorium_config_directory_mode, and scriptorium_config_file_mode. The standalone defaults are root:root, directory mode 0755, and file mode 0644; composing roles may override this generic configuration interface. Non-null falsey values are retained. scriptorium_backends 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:

scriptorium_backends: "{{ scriptorium_local_backends | combine(scriptorium_remote_backends) }}"

Backend entries may name a credential environment variable through api_key_env; credential values themselves belong outside this role. The role does not install prompt, profile, or schema content and does not manage a service.

Example

- hosts: scriptorium_hosts
  roles:
    - role: ansible-role-scriptorium

Validation

The repository-local integration suite installs its pinned collection and runs syntax checking and production-profile lint. It applies the default role, uses an offline native profile inspection with the managed configuration, and then requires clean repeated convergence. It also combines missing-binary recovery with a caller-supplied Go executable while dependency management is disabled, and covers one representative configuration with null omission, intentional zero and false values, backend pass-through, and offline native inspection. It mutates only the managed source, binary, configuration, and a private temporary directory, then restores the default deployment during cleanup.

tests/integration