hal-guide

# HAL repository guide ## Repository map | Path | Purpose | |------|---------| | `README.md` | Entry point: what the repo is, projects table with statuses and versions, architecture diagram | | `docs/handbook.md` | How the team works: organisation, stack, git workflow, testing, open improvement topics | | `docs/weekly/`, `docs/monthly/` | Meeting notes (one file per week) and monthly reports | | `docs/async.md`, `docs/interviews.md`, `docs/2025-09-team-workshop.md` | Process documents and retrospectives | | `docs/radicle.md` | Radicle evaluation; ends with the November 2025 decision to stop using it | | `docs/homebrew.md` | How to add formulae to the team's Homebrew tap (notunrandom/homebrew-cardano) | | `docs/crypto/` | ZKP learning material: gitbook.md (SageMath/Rust/Zig exercises), journal.md, training slides | | `docs/deployment/anti-services.md` | Historical: pre-rename Moog ("anti") deployment; superseded by `infrastructure/moog/` | | `infrastructure/mpfs/` | Preprod MPFS compose stack: cardano-node, Ogmios, Yaci Store + PostgreSQL, MPFS, autoheal | | `infrastructure/moog/{agent,oracle}/` | Moog agent and oracle compose files, pinned to released images | | `infrastructure/gatus/{mpfs,agent,oracle}/` | Per-host Gatus monitoring configs with Telegram alerting | | `infrastructure/scripts/node-currency-check.sh` | Cron script alerting when a running cardano-node image lags the latest release | | `templates/README.md` | README template for new HAL projects | ## Build, test, run Nothing builds or runs locally; there is no CI, no flake, no test suite. The only executable content is the deployment configuration, which runs on three CF preprod hosts from a `/opt/hal` checkout: - MPFS host (10.1.21.21): `cd /opt/hal/infrastructure/mpfs && docker compose up -d` (after the Mithril bootstrap and secret files described in `infrastructure/mpfs/README.md`) - Agent host (10.1.21.20): `cd /opt/hal/infrastructure/moog/agent && docker compose up -d` - Oracle host (10.1.21.19): `cd /opt/hal/infrastructure/moog/oracle && docker compose up -d` Do not run these on a development machine: they mount host paths (`/opt/mpfs/...`) and secret files (`/home/paolino/secrets/...`) that only exist on those hosts. ## Navigating the code - For deployment facts (image versions, ports, networks, secrets paths), the compose files are the source of truth: `infrastructure/mpfs/docker-compose.yml`, `infrastructure/moog/*/docker-compose.yaml`, `infrastructure/gatus/*/docker-compose.yaml`. - Yaci Store indexer settings (sync start slot, enabled stores, Ogmios URL) are in `infrastructure/mpfs/application.properties`. - Monitoring conditions (what fires a Telegram alert) are in `infrastructure/gatus/*/config.yaml`. - The node config files in `infrastructure/mpfs/configs/` come from book.play.dev.cardano.org; `configs/download.sh` refreshes them. - Team decisions and their history live in `docs/` (handbook for current practice, weekly/monthly notes for when something changed). ## Using the artifacts This repo is consumed by reading, not installing. Typical operations: - Deploy or update a service: follow the README next to its compose file (`infrastructure/{mpfs,moog/agent,moog/oracle}/README.md`); always `docker compose` from the `/opt/hal` checkout directory. - Bootstrap a fresh MPFS node database: `source infrastructure/mpfs/bootstrap.sh` (requires a local `.env` defining `MPFS_DIR`; downloads a Mithril preprod snapshot). - Check monitoring: Gatus web UI on the MPFS host listens on port 8090; alerts go to Telegram. - Test the currency check without sending alerts: `DRY_RUN=1 infrastructure/scripts/node-currency-check.sh <telegram-env-file>`. ## Answering questions - "What does the HAL team work on?" → the Projects table in `README.md` (status icons + pinned versions; verify versions against GitHub releases before quoting them, they age). - "How does the team work / what's the process?" → `docs/handbook.md`; open questions are in its WIP section and in `docs/interviews.md`. - "What runs in preprod / what is deployed where?" → `infrastructure/README.md` (host table + architecture diagram), then the per-service compose files. - "Why did an alert fire?" → `infrastructure/gatus/*/config.yaml` for the condition; `infrastructure/scripts/node-currency-check.sh` for release-lag warnings. - "What is MPFS / Moog?" → one-liners in the Projects table; the real docs are in their own repos (cardano-foundation/mpfs, cardano-foundation/moog). - "Did the team adopt Radicle?" → no; `docs/radicle.md`, November 2025 decision.