# Ansible Role: Scriptorium

Installs and configures [Scriptorium](https://gitea.maximumdirect.net/eric/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

```yaml
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_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` as `root:root` mode `0644`. 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:

```yaml
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

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

## Validation

The repository-local integration suite installs its pinned collection, runs
syntax checking and production-profile lint, and applies the default role. It
uses an offline native profile inspection with the managed configuration, then
requires clean repeated convergence. It mutates only the managed source,
binary, configuration, and a private temporary directory, then restores the
default deployment during cleanup.

```sh
tests/integration
```

Ansible role to install the Scriptorium application.