79 lines
4.2 KiB
Markdown
79 lines
4.2 KiB
Markdown
# 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):
|
|
```bash
|
|
ansible-navigator run playbooks/<name>.yml --mode stdout
|
|
```
|
|
|
|
Run with extra vars (required by several playbooks):
|
|
```bash
|
|
ansible-navigator run playbooks/deploy_application.yml --mode stdout -e artifact_url=<url>
|
|
```
|
|
|
|
Lint all playbooks:
|
|
```bash
|
|
ansible-navigator lint playbooks/ --mode stdout
|
|
```
|
|
|
|
Install required collections:
|
|
```bash
|
|
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 |