Install and configure Scriptorium

README.md

@@ -1,3 +1,78 @@
-# ansible-role-scriptorium
+# Ansible Role: Scriptorium
 
-Ansible role to install the Scriptorium application.
+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.