local-network

A local Graph network for debugging & integration tests.

Usage

Requires Docker & Docker Compose v2.24+ and just.

# Show all recipes
just --list

# Start (or resume) the network — skips already-completed setup steps
just up

# Rebuild a single service after code changes
just up --build ${service}

# Get logs for a service
just logs ${service}

# Re-initialise from scratch (removes all persisted state)
just reset && just up

Note: State is persisted in named volumes, so the network restarts where it left off. Use just reset only when you want a clean slate.

More useful commands for each component can be found at CHEATSHEET.md.

Configuration

The .env file holds all configuration and is read by three consumers:

• docker-compose — for ${VAR} substitution in docker-compose.yaml (auto-loaded from the project directory).
• host scripts — scripts that run on the host source this file via source .env.
• containers — volume-mounted at /opt/config/.env and typically sourced by each service's run.sh.

Local Overrides

Create .env.local (gitignored) to override defaults without touching .env:

# .env.local — your local settings
COMPOSE_PROFILES=rewards-eligibility,block-oracle,explorer,indexing-payments
GRAPH_NODE_VERSION=v0.38.0-rc1

.env.local overrides .env for:

• docker compose but only when invoked via just. Bare docker compose reads only .env.
• host scripts (typically sourced automatically after .env)
• it DOES NOT override .env for container scripts.

Service Profiles

Optional services are controlled via COMPOSE_PROFILES in .env. By default, profiles that work out of the box are enabled:

COMPOSE_PROFILES=block-oracle,explorer

Available profiles:

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)

To enable all profiles, uncomment the full line in .env:

COMPOSE_PROFILES=rewards-eligibility,block-oracle,explorer,indexing-payments

GHCR authentication (indexing-payments)

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:

echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin

Then set the image versions in .env or .env.local:

DIPPER_VERSION=<tag>
IISA_VERSION=<tag>

Building from source - Dev overrides (compose/dev/)

For local development, mount locally-built binaries into running containers. Set COMPOSE_FILE in .env (or .env.local, when using just) to include dev override files:

# 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

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 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:

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.

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.