Profile recipes

.gitignore

@@ -3,10 +3,20 @@
 .claude
 .idea
 
-# Environment overrides
+# Environment files
+# .env: auto-generated by scripts/resolve-recipe.sh from a recipe; picked up
+# automatically by `docker compose`. Regenerate with `just resolve` or `just up`.
+# .env.local: optional per-checkout overrides (highest precedence in the resolver).
+# .env.secrets: optional secrets fragment (legacy; new code uses .env.local).
+.env
 .env.local
 .env.secrets
 
+# Recipe selection: .recipe (optional, committed per-branch default — branches
+# pin their target scenario by committing one); .recipe.local (per-checkout
+# override, never committed).
+.recipe.local
+
 # OS
 .DS_Store
 Thumbs.db
@@ -20,6 +30,12 @@ Thumbs.db
 # Rust build artifacts
 tests/target/
 
+# State dumps from scripts/dump-state.sh (captured for offline debugging)
+_dumps/
+
+# Volume snapshots from scripts/bake-snapshot.sh
+_snapshots/
+
 # Legacy local config directory (now uses config-local Docker volume)
 config/local/
 

CHEATSHEET.md

@@ -129,4 +129,3 @@ curl "http://localhost:7700/api/subgraphs/id/BFr2mx7FgkJ36Y6pE5BiXs1KmNUmVDCnL82
 ```bash
 docker exec -it redpanda rpk topic consume gateway_client_query_results --brokers="localhost:9092"
 ```
-

README.md

@@ -2,120 +2,137 @@
 
 A local Graph network for debugging & integration tests.
 
-## Usage
+Requires Docker & Docker Compose v2.24+, plus [`just`](https://github.com/casey/just)
+for the entry-point commands.
 
-Requires Docker & Docker Compose v2.24+.
+## Quick start
 
 ```bash
-# Start (or resume) the network — skips already-completed setup steps
-docker compose up -d
-
-# Re-initialise from scratch (removes all persisted state)
-docker compose down -v && docker compose up -d
+just up           # resolve active recipe → .env, then docker compose up -d --build
+just down         # docker compose down
+just logs gateway # docker compose logs -f gateway
 ```
 
-State (chain, postgres, ipfs) is persisted in named volumes, so the network
-restarts where it left off. Use `down -v` only when you want a clean slate.
-
-Add `--build` to rebuild after changes to Docker build context, including modifying `run.sh` or `Dockerfile`, or changed source code.
-
-## Useful commands
+The first `just up` materialises a recipe (see below) into a gitignored `.env`
+file. After that, bare `docker compose` commands work directly — `just up` just
+chains recipe resolution + a build-aware compose up. `docker compose` halts
+with a clear error if `.env` is missing.
 
-- `docker compose up -d --build ${service}` — rebuild a single service after code changes
-- `docker compose logs -f ${service}`
-- `source .env`
+## Recipes
 
-Useful commands for each component can be found at [CHEATSHEET.md](CHEATSHEET.md)
+A **recipe** selects which env fragments compose, which compose profiles enable,
+and which image versions pin. Recipes live in [recipes/](recipes/) and reference
+fragments in [config/](config/).
 
-## Local Overrides
-
-Create `.env.local` (gitignored) to override defaults without touching `.env`:
+| Recipe              | Profile set                                       | Includes                                                                                      |
+| ------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `baseline`          | `block-oracle,explorer,rewards-eligibility`       | Full GIP-0088 contract deployment (REO + IA + RAM) on stable image versions                   |
+| `indexing-payments` | `explorer,rewards-eligibility,indexing-payments`  | Baseline + WIP DIPs services (dipper, IISA, indexing-payments subgraph, dips-fork indexer-rs) |
 
 ```bash
-# .env.local — your local settings
-COMPOSE_PROFILES=rewards-eligibility,block-oracle,explorer,indexing-payments
-GRAPH_NODE_VERSION=v0.38.0-rc1
+just recipes                 # list available recipes
+just recipe-active           # show which one is currently selected
+just up indexing-payments    # one-shot recipe override
+echo indexing-payments > .recipe.local  # per-checkout sticky default (gitignored)
 ```
 
-Host scripts source `.env.local` automatically after `.env`.
+Recipe selection precedence: CLI arg → `RECIPE` env → `.recipe.local` →
+`.recipe` (committed per-branch default) → `baseline`.
+
+To add a recipe, create `recipes/my-recipe.json` with the fragments + override
+`env` to apply. See existing JSON files for the shape.
 
-## Service Profiles
+## Local overrides
 
-Optional services are controlled via `COMPOSE_PROFILES` in `.env`.
-By default, profiles that work out of the box are enabled:
+Create `.env.local` (gitignored) for machine-specific values that layer on top
+of the resolved recipe — image-tag overrides, compose-profile additions, etc:
 
 ```bash
-COMPOSE_PROFILES=rewards-eligibility,block-oracle,explorer
+# .env.local
+GRAPH_NODE_VERSION=v0.43.0
+COMPOSE_PROFILES=block-oracle,explorer,rewards-eligibility,indexing-payments,my-extra
 ```
 
-Available profiles:
+`.env.local` is sourced last during recipe resolution, so its values win.
 
-| Profile               | Services                          | Prerequisites              |
-| --------------------- | --------------------------------- | -------------------------- |
-| `block-oracle`        | block-oracle                      | none                       |
-| `explorer`            | block-explorer UI                 | none                       |
-| `rewards-eligibility` | eligibility-oracle-node           | none (clones from GitHub)  |
-| `indexing-payments`   | dipper, iisa, iisa-scoring        | GHCR auth (below)          |
+## Iterating on upstream source
 
-To enable all profiles, uncomment the full line in `.env`:
+Most services run from prebuilt images pinned by `${SERVICE_VERSION}` vars
+in [config/services.env](config/services.env) and
+[config/indexing-payments.env](config/indexing-payments.env). To iterate on
+upstream source, build a locally-tagged image in the upstream repo and
+override the version pin in `.env.local`:
 
 ```bash
-COMPOSE_PROFILES=rewards-eligibility,block-oracle,explorer,indexing-payments
+# .env.local
+INDEXING_PAYMENTS_SUBGRAPH_VERSION=local
 ```
 
-### GHCR authentication (indexing-payments)
+Then `just rebuild <service>` here to pick up the change.
 
-The `indexing-payments` profile pulls private images from `ghcr.io/edgeandnode`.
-Create a GitHub **classic** Personal Access Token with `read:packages` scope
-(https://github.com/settings/tokens — fine-grained tokens do not support packages) and log in once:
+How each upstream produces a `:local` tag is repo-specific. Convention is a
+`just build-image` recipe that tags `<image>:local` — e.g.
+graphprotocol/indexing-payments-subgraph builds
+`ghcr.io/graphprotocol/indexing-payments-subgraph:local` via its `justfile`.
+
+## Rebuilding after edits
 
 ```bash
-echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin
+just rebuild indexer-agent       # rebuild + restart one service
+just rebuild                     # rebuild + restart all
+just up                          # equivalent if recipe hasn't changed (defaults to --build)
 ```
 
-Then set the image versions in `.env` or `.env.local`:
+`run.sh` and `Dockerfile` changes only take effect after a rebuild.
+
+## State persistence
+
+Volumes (`chain-data`, `postgres-data`, `ipfs-data`, `redpanda-data`,
+`iisa-scores`, `config-local`) survive `just down`. To start clean:
 
 ```bash
-DIPPER_VERSION=<tag>
-IISA_VERSION=<tag>
+just reset      # docker compose down -v
+just up
 ```
 
-## Building from source - Dev overrides (compose/dev/)
+## GHCR authentication (indexing-payments)
 
-For local development, mount locally-built binaries into running containers.
-Set `COMPOSE_FILE` in `.env` to include dev override files:
+The `indexing-payments` profile pulls private images from `ghcr.io/edgeandnode`.
+Create a GitHub **classic** Personal Access Token with `read:packages` scope
+([fine-grained tokens don't support packages](https://github.com/settings/tokens))
+and log in once:
 
 ```bash
-# Mount local indexer-service binary
-INDEXER_SERVICE_BINARY=/path/to/indexer-rs/target/release/indexer-service-rs
-COMPOSE_FILE=docker-compose.yaml:compose/dev/indexer-service.yaml
-
-# Multiple overrides
-COMPOSE_FILE=docker-compose.yaml:compose/dev/indexer-service.yaml:compose/dev/tap-agent.yaml
+echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin
 ```
 
-Each override requires a binary path env var. Source repos own their own build;
-local-network just wraps the published image with `run.sh` and utilities.
-See [compose/dev/README.md](compose/dev/README.md) for details.
-
 ## Devcontainer usage
 
-When running inside a devcontainer, service names (gateway, redpanda, etc.) won't resolve by default because the devcontainer is on a different Docker network. Connect it to the compose network once per session:
+Inside a devcontainer, service names won't resolve by default because the
+devcontainer is on a different Docker network. Connect once per session:
 
 ```bash
 scripts/connect-network.sh
 ```
 
-The script auto-detects the compose project network. You can also pass a network name explicitly: `scripts/connect-network.sh my-network_default`.
+The script auto-detects the compose project network. Pass a name explicitly with
+`scripts/connect-network.sh my-network_default`.
+
+## Component cheatsheet
+
+See [CHEATSHEET.md](CHEATSHEET.md) for per-component commands.
 
 ## Common issues
 
 ### `too far behind`
 
-Gateway error:
-
 ```
 ERROR graph_gateway::network::subgraph_client: network_subgraph_query_err="response too far behind"
 ```
 
-This happens when subgraphs fall behind the chain head. With automine (default), this is a harmless warning during startup. Run `scripts/mine-block.sh 10` to advance blocks manually if needed.
+Subgraphs fell behind the chain head. With automine (default), this is harmless
+during startup. `scripts/mine-block.sh 10` to advance blocks manually.
+
+### `LOCAL_NETWORK_RECIPE is missing a value`
+
+`.env` hasn't been generated yet. Run `just resolve` (or any `just up`).

compose/dev/indexer-agent.yaml

@@ -11,7 +11,7 @@ services:
   indexer-agent:
     entrypoint: bash -cl /opt/run-override.sh
     ports:
-      - "${INDEXER_MANAGEMENT}:7600"
+      - "${INDEXER_MANAGEMENT_PORT}:7600"
       # Nodejs debugger
       - 9230:9230
     volumes: