cardano-foundation 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 ininfrastructure/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.shrefreshes 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); alwaysdocker composefrom the/opt/halcheckout directory. - Bootstrap a fresh MPFS node database:
source infrastructure/mpfs/bootstrap.sh(requires a local.envdefiningMPFS_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 indocs/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.yamlfor the condition;infrastructure/scripts/node-currency-check.shfor 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.