A reporting tool for Ascender. Ledger accepts the log stream from one or more Ascender servers, stores the host facts and the changes each playbook run made, and lets you report across both. Recording only changes strips out the noise of unchanged tasks, so what remains is what your automation actually did.
- A running Ascender server configured to send its log stream to Ledger
- Docker with Compose, for a standalone deployment
- A Kubernetes cluster, if deploying through the installer
Ledger is normally deployed alongside Ascender by the Ascender installer, by setting LEDGER_INSTALL: true. To run it standalone:
docker compose up -dOnce Ascender is sending its log stream with Ledger's token, Ledger records two kinds of data as jobs run, both searchable from the web interface.
Fact data is collected from any module that writes to ansible_facts. That covers the setup module used by gather_facts, modules that register facts automatically such as several of the Windows modules, and set_fact.
set_fact is deliberately allowed, so you can build custom facts in a playbook and report on them. A whitelist for restricting which modules contribute facts is planned.
Only changes are recorded. If a job template has Show Changes enabled and the module supports it, such as lineinfile, Ledger stores a diff of exactly what changed.
The search box searches the change data itself, so you can ask which automated changes touched /etc/sudoers.
Both kinds of data can be saved as a report, which is shared with other users and mailed on a schedule.
A facts report picks the facts to show as its columns and selects hosts by comparing their fact values. A changes report lists the changes the way the Changes page does, narrowed by the same filters: host, job template, playbook, role, module, job type, inventory, project and a search of the change data. It also takes a window in hours, so a scheduled report covers the changes of the last night rather than everything ever recorded.
Ascender authenticates to Ledger with a token, so it keeps working when Ascender's pods are rescheduled and come back with new addresses.
- Copy the Authorization Token from Admin, Settings, General in Ledger
- In Ascender, under Settings, Logging, set Logging Aggregator Type to
ledgerand paste the token into Logging Aggregator Password / Token - The server appears under Admin, Servers as soon as it sends data, identified by its install UUID. Edit the entry to change the Ascender URL that changes link back to; it is filled in from Ascender's own URL when Ascender sends one
Require Token Authorization is off by default, so an upgraded Ledger keeps receiving data until Ascender has the token. The Servers page shows whether each server is sending a valid token; once they all are, turn it on under Settings, General, and Ledger refuses data without the token from then on. The most recent refusal is shown on the dashboard and the Servers page. Reset Token issues a new token, after which each Ascender server needs the new one.
Container configuration lives in files/, and credentials are passed as Docker secrets rather than environment values. secrets/admin_password.txt seeds the initial admin account, and the MySQL password is read from /run/secrets/db-ledger-password.
Ledger runs as three containers, published under ghcr.io/ctrliq/ascender-ledger:
ledger-web: the reporting interface, served by nginx and PHP-FPMledger-parser: receives and parses the incoming log stream from Ascenderledger-db: the MySQL database holding facts and changes
| Repository | Description |
|---|---|
| ascender | The platform itself: web UI, REST API, and task engine |
| ascender-install | Installer for Ascender and Ledger, with Galaxy Proxy support |
| ascender-k8s-install | Kubernetes installer for Ascender, Ledger, and React |
| ascender-pro-install | Enhanced installer adding Reaqt, Registry, and Galaxy Proxy |
| ascender-operator | Kubernetes operator that deploys and manages Ascender |
| ascender-ee | Default execution environment image for Ascender jobs |
| ascender-kit | The ascender command line client and Python API library |
| ascender-collection | The ctrliq.ascender Ansible collection for a controller |
| ascender-mcp | MCP server that lets AI agents drive Ascender through its REST API |
| ascender-ledger | Reporting tool for host facts and playbook changes |
| ascender-galaxy-proxy | Caching proxy for Ansible Galaxy collection downloads |
| ascender-playbooks | Example playbooks for use with Ascender |
- See CONTRIBUTING.md for development setup, testing, and pull requests.
- Report bugs and feature ideas via GitHub Issues.
- For security vulnerabilities, follow SECURITY.md rather than opening an issue.
- Join the Ascender forum to discuss development topics.
Licensed under the Apache License 2.0. See LICENSE.md and COPYRIGHT.md.