bab-backend-ansible/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Does

Ansible automation for the BAB (Borrow a Boat) project backend. Manages the full lifecycle of an Appwrite-based backend running on a single RHEL 9 host (bab1.mgmt.toal.ca) via Ansible Automation Platform. Do not refer to AWX. Also contains Ansible EDA rulebooks for event-driven automation triggered by Gitea webhooks and Alertmanager alerts.

Common Commands

Run a playbook via ansible-navigator (preferred — uses execution environment):

ansible-navigator run playbooks/<name>.yml --mode stdout

Run with extra vars (required by several playbooks):

ansible-navigator run playbooks/deploy_application.yml --mode stdout -e artifact_url=<url>

Lint all playbooks:

ansible-navigator lint playbooks/ --mode stdout

Install required collections:

ansible-galaxy collection install -r requirements.yml

Architecture

Inventory and Credentials

There is no inventory file in this repo. For development, a static inventory is located in ~/Dev/inventories/bab-inventory/. In production, inventory and credentials (Appwrite API keys, ServiceNow instance, vault password) are managed externally in AAP.

Sensitive files are gitignored: ansible.cfg, secrets.yml, .vault_password.

Playbook Roles

Playbook	Purpose	Notable vars
install_appwrite.yml	Full RHEL 9 host setup: Docker, Appwrite container via compose	—
install_nginx.yml	Nginx via nginxinc.nginx_core role + firewalld	—
configure_act_runner.yml	Gitea Act Runner as systemd user unit (rootless)	runner_user
deploy_application.yml	Downloads a release tarball and extracts to nginx webroot	artifact_url
provision_database.yml	Creates Appwrite database, collections, and attributes via REST API	Appwrite vars
provision_users.yml	Creates users in Appwrite via REST API (Argon2 hashed)	bab_users list
load_data.yml	Loads seed data from playbooks/files/database/*.json into Appwrite	Appwrite vars
read_database.yml	Dumps Appwrite collection data to playbooks/files/database/	Appwrite vars, targets appwrite:&dev
clean_logs.yml	Removes large test log files from /var/log	—
investigate_high_cpu.yml	Captures process data and opens ServiceNow incident + problem	snow_instance, EDA event vars
update_certificates.yml	Requests and installs TLS certs from Red Hat IdM (IPA)	ipa_admin_password, cert path vars

Event-Driven Ansible (EDA) Rulebooks

rulebooks/gitea_webhook.yml — listens for Gitea push webhooks carrying an artifact_url and triggers the bab-deploy-application AAP job template.

rulebooks/alertmanager_listener.yml — listens on port 9101 for Prometheus Alertmanager events; routes to AAP job templates for log cleanup (root filesystem over 80% full) and CPU investigation (ProcessCPUHog). Scoped to org == "OYS".

Appwrite API Pattern

Playbooks that talk to Appwrite use ansible.builtin.uri delegated to localhost, with module_defaults at the play level to set shared headers (X-Appwrite-Project, X-Appwrite-Key, X-Appwrite-Response-Format). All mutating calls use status_code: [201, 409] to tolerate re-runs — but true idempotency is incomplete (noted in provision_database.yml).

Templates and Static Files

• playbooks/templates/ — Jinja2 templates: act_runner.service (systemd unit for Gitea runner), appwrite_attribute_template.json.j2 (Appwrite schema helper), cpuhog_ticket.j2 (ServiceNow ticket body)
• playbooks/files/database/ — JSON seed data files used by load_data.yml and written by read_database.yml

Collections Used

• community.docker — Docker image pulls and container management
• community.general — RHSM repo management
• ansible.posix — firewalld
• nginxinc.nginx_core — Nginx install and config roles
• servicenow.itsm — Incident and problem creation
• redhat.rhel_idm — IPA certificate requests
• community.crypto — TLS key/CSR generation
• ansible.utils — remove_keys filter used in load_data.yml
• ansible.eda — webhook and alertmanager sources