oys/bab-backend-ansible
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Got things working. Added CLAUDE instructions

Browse Source
This commit is contained in:
Patrick Toal
2026-03-14 13:48:23 -04:00
parent 2ab06e86f8
commit 1622177ba0
17 changed files with 1190 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
CLAUDE.md
View File

@@ -1,79 +1,52 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Session Start
## What This Repo Does
Read the latest handoff in docs/summaries/ if one exists. Load only the files that handoff references — not all summaries. If no handoff exists, ask: what is the goal this session and what is the target deliverable.
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.
Before starting work, state: what you understand the project state to be, what you plan to do this session, and any open questions.
## Common Commands
## Identity
Run a playbook via ansible-navigator (preferred — uses execution environment):
```bash
ansible-navigator run playbooks/<name>.yml --mode stdout
```
You work with Patrick, a Solutions Architect. This repo is Ansible automation for the BAB (Borrow a Boat) backend — an Appwrite-based service on a single RHEL 9 host (`bab1.mgmt.toal.ca`). Automation runs via Ansible Automation Platform (AAP) in production, ansible-navigator locally. Patrick has expert-level Ansible knowledge — do not explain Ansible basics.
Run with extra vars (required by several playbooks):
```bash
ansible-navigator run playbooks/deploy_application.yml --mode stdout -e artifact_url=<url>
```
## Project
Lint all playbooks:
```bash
ansible-navigator lint playbooks/ --mode stdout
```
**Repo:** Ansible playbooks and EDA rulebooks managing a full Appwrite backend lifecycle on RHEL 9.
**Host:** `bab1.mgmt.toal.ca`
**Run locally:** `ansible-navigator run playbooks/<name>.yml --mode stdout`
**Run with extra vars:** `ansible-navigator run playbooks/deploy_application.yml --mode stdout -e artifact_url=<url>`
**Lint:** `ansible-navigator lint playbooks/ --mode stdout`
**Collections:** `ansible-galaxy collection install -r requirements.yml`
Install required collections:
```bash
ansible-galaxy collection install -r requirements.yml
```
Load `docs/context/architecture.md` when working on playbooks, EDA rulebooks, or Appwrite API tasks.
## Architecture
## Rules
### 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.
1. Do not mix unrelated project contexts in one session.
2. Write state to disk, not conversation. After completing meaningful work, write a summary to docs/summaries/ using templates from templates/claude-templates.md. Include: decisions with rationale, exact numbers, file paths, open items.
3. Before compaction or session end, write to disk: every number, every decision with rationale, every open question, every file path, exact next action.
4. When switching work types (development → documentation → review), write a handoff to docs/summaries/handoff-[date]-[topic].md and suggest a new session.
5. Do not silently resolve open questions. Mark them OPEN or ASSUMED.
6. Do not bulk-read documents. Process one at a time: read, summarize to disk, release from context before reading next. For the detailed protocol, read docs/context/processing-protocol.md.
7. Sub-agent returns must be structured, not free-form prose. Use output contracts from templates/claude-templates.md.
Sensitive files are gitignored: `ansible.cfg`, `secrets.yml`, `.vault_password`.
## Where Things Live
### Playbook Roles
- `templates/claude-templates.md` — summary, handoff, decision, analysis, task, output contract templates (read on demand)
- `docs/summaries/` — active session state (latest handoff + decision records + source summaries)
- `docs/context/` — reusable domain knowledge, loaded only when relevant
- `architecture.md` — playbook inventory, EDA rulebooks, Appwrite API pattern, collections
- `processing-protocol.md` — full document processing steps
- `archive-rules.md` — summary lifecycle and file archival rules
- `subagent-rules.md` — when to use subagents vs. main agent
- `docs/archive/` — processed raw files. Do not read unless explicitly told.
- `output/deliverables/` — final outputs
| 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 |
## Error Recovery
### Event-Driven Ansible (EDA) Rulebooks
If context degrades or auto-compact fires unexpectedly: write current state to docs/summaries/recovery-[date].md, tell the user what may have been lost, suggest a fresh session.
`rulebooks/gitea_webhook.yml` — listens for Gitea push webhooks carrying an `artifact_url` and triggers the `bab-deploy-application` AAP job template.
## Before Delivering Output
`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
Verify: exact numbers preserved, open questions marked OPEN, output matches what was requested (not assumed), no Ansible idempotency regressions introduced, summary written to disk for this session's work.