Docker Setup

Complete guide to running Graph Node with Docker and Docker Compose

This guide covers running Graph Node using prebuilt Docker images, either with Docker Compose for a complete local setup or standalone with existing infrastructure.

Prerequisites

Before starting, ensure you have:

• Docker: Install Docker
• Docker Compose: Install Docker Compose
• Ethereum Node: Access to an Ethereum RPC endpoint (local node or provider)
• Sufficient Resources: At least 4GB RAM and 50GB disk space

Docker Compose Setup

Docker Compose provides the easiest way to run Graph Node locally with all required services.

1. Clone the Repository

   First, get the Graph Node repository:

   git clone https://github.com/graphprotocol/graph-node.git
   cd graph-node/docker
   
2. Configure Ethereum Connection

   Edit docker-compose.yml to set your Ethereum node endpoint. By default, it connects to mainnet:http://host.docker.internal:8545.

   environment:
     ethereum: 'mainnet:http://host.docker.internal:8545'
   

   Replace with your network and RPC URL:

   • Local node: mainnet:http://host.docker.internal:8545
   • Infura: mainnet:https://mainnet.infura.io/v3/YOUR-PROJECT-ID
   • Alchemy: mainnet:https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY
   • Multiple networks: mainnet:http://...,sepolia:http://...

   Example: Multiple Networks

   environment:
     ethereum: 'mainnet:https://mainnet.infura.io/v3/PROJECT-ID,sepolia:https://sepolia.infura.io/v3/PROJECT-ID'
   
3. Start the Services

   Launch all services (Graph Node, PostgreSQL, IPFS):

   docker-compose up
   

   For background execution:

   docker-compose up -d
   

   This creates persistent data directories:

   • ./data/ipfs - IPFS data
   • ./data/postgres - PostgreSQL database
4. Verify Services

   Check that all services are running:

   docker-compose ps
   

   Access the endpoints:

   • GraphiQL Interface: http://localhost:8000
   • HTTP Queries: http://localhost:8000/subgraphs/name/<subgraph-name>
   • WebSocket: ws://localhost:8001/subgraphs/name/<subgraph-name>
   • Admin API: http://localhost:8020
   • IPFS: http://127.0.0.1:5001

Docker Compose Configuration

The complete docker-compose.yml configuration:

version: '3'
services:
  graph-node:
    image: graphprotocol/graph-node
    ports:
      - '8000:8000'  # GraphQL HTTP server
      - '8001:8001'  # GraphQL WebSocket server
      - '8020:8020'  # JSON-RPC admin server
      - '8030:8030'  # Indexing status server
      - '8040:8040'  # Metrics server
    depends_on:
      - ipfs
      - postgres
    extra_hosts:
      - host.docker.internal:host-gateway
    environment:
      postgres_host: postgres
      postgres_user: graph-node
      postgres_pass: let-me-in
      postgres_db: graph-node
      ipfs: 'ipfs:5001'
      ethereum: 'mainnet:http://host.docker.internal:8545'
      GRAPH_LOG: info
  ipfs:
    image: ipfs/kubo:v0.17.0
    ports:
      - '5001:5001'
    volumes:
      - ./data/ipfs:/data/ipfs:Z
  postgres:
    image: postgres
    ports:
      - '5432:5432'
    command:
      [
        "postgres",
        "-cshared_preload_libraries=pg_stat_statements",
        "-cmax_connections=200"
      ]
    environment:
      POSTGRES_USER: graph-node
      POSTGRES_PASSWORD: let-me-in
      POSTGRES_DB: graph-node
      PGDATA: "/var/lib/postgresql/data"
      POSTGRES_INITDB_ARGS: "-E UTF8 --locale=C"
    volumes:
      - ./data/postgres:/var/lib/postgresql/data:Z

Port Reference

8000 · HTTP

GraphQL HTTP server for querying subgraphs

8001 · WebSocket

GraphQL WebSocket server for subscriptions

8020 · JSON-RPC

Admin API for managing subgraphs

8030 · HTTP

Indexing status and metrics

8040 · HTTP

Prometheus metrics endpoint

Running with Existing Infrastructure

If you already have PostgreSQL and IPFS running, use the standalone Docker image:

docker run -it \
  -e postgres_host=<HOST> \
  -e postgres_port=<PORT> \
  -e postgres_user=<USER> \
  -e postgres_pass=<PASSWORD> \
  -e postgres_db=<DBNAME> \
  -e ipfs=<HOST>:<PORT> \
  -e ethereum=<NETWORK_NAME>:<ETHEREUM_RPC_URL> \
  -p 8000:8000 \
  -p 8001:8001 \
  -p 8020:8020 \
  -p 8030:8030 \
  graphprotocol/graph-node:latest

Example: Connecting to External Services

docker run -it \
  -e postgres_host=my-postgres.example.com \
  -e postgres_port=5432 \
  -e postgres_user=graph \
  -e postgres_pass=secret123 \
  -e postgres_db=graph-node \
  -e ipfs=ipfs.infura.io:5001 \
  -e ethereum=mainnet:https://mainnet.infura.io/v3/YOUR-PROJECT-ID \
  -p 8000:8000 \
  graphprotocol/graph-node:latest

Environment Variables

postgres_host · string · required

PostgreSQL server hostname

postgres_port · number · default: "5432"

PostgreSQL server port

postgres_user · string · required

Database username

postgres_pass · string · required

Database password

postgres_db · string · required

Database name

postgres_args · string · default: "sslmode=prefer"

Additional PostgreSQL connection arguments

ipfs · string · required

IPFS node address (e.g., ipfs:5001 or 127.0.0.1:5001)

ethereum · string · required

Ethereum networks in format NAME:URL. Multiple networks separated by commas.

Example: mainnet:http://localhost:8545,sepolia:https://sepolia.infura.io/v3/KEY

node_role · string · default: "combined-node"

Node role: combined-node, index-node, or query-node

node_id · string · default: "default"

Unique identifier for this node

GRAPH_LOG · string · default: "info"

Log level: error, warn, info, debug, trace

GRAPH_NODE_CONFIG · string

Path to advanced TOML configuration file (optional)

disable_core_dumps · boolean

Set to any value to disable core dumps (useful for query nodes with large caches)

Apple Silicon (M1/M2) Support

Graph Node doesn’t provide native ARM64 images. On Apple Silicon Macs, build locally:

1. Increase Docker Memory

   Open Docker Desktop → Settings → Resources → Advanced → Memory

   Set to at least 8GB to avoid build failures.

2. Remove Existing Image

   docker rmi graphprotocol/graph-node:latest
   
3. Build for ARM64

   cd graph-node
   ./docker/build.sh
   docker tag graph-node graphprotocol/graph-node:latest
   
4. Run Docker Compose

   cd docker
   docker-compose up
   

Using Configuration Files

For advanced setups (multiple databases, custom chain configs), use a TOML configuration file:

docker run -it \
  -v /path/to/config.toml:/etc/graph-node/config.toml \
  -e GRAPH_NODE_CONFIG=/etc/graph-node/config.toml \
  -e ipfs=ipfs:5001 \
  -p 8000:8000 \
  graphprotocol/graph-node:latest

See the Configuration Overview for details on the TOML format.

Deploying Subgraphs

Once Graph Node is running, deploy subgraphs using Graph CLI:

1. Install Graph CLI

   npm install -g @graphprotocol/graph-cli
   
2. Create Subgraph

   graph init --studio my-subgraph
   cd my-subgraph
   
3. Build and Deploy

   graph codegen
   graph build
   graph create --node http://localhost:8020/ my-subgraph
   graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 my-subgraph
   

Troubleshooting

Connection refused to Ethereum node

If using host.docker.internal, ensure your Ethereum node binds to 0.0.0.0, not just 127.0.0.1.

On Linux, host.docker.internal may not work. Use the host’s IP address instead:

ethereum: 'mainnet:http://192.168.1.100:8545'

PostgreSQL connection errors

Ensure PostgreSQL allows connections from Docker containers. Check pg_hba.conf and verify the container can reach the host:

docker-compose exec graph-node nc -zv postgres 5432

IPFS timeout errors

Verify IPFS is accessible:

curl http://localhost:5001/api/v0/version

If using external IPFS, ensure it’s publicly accessible or on the same network.

Out of memory errors

Increase Docker’s memory limit:

• Docker Desktop: Settings → Resources → Advanced → Memory (set to 8GB+)
• Linux: Edit /etc/docker/daemon.json to increase memory limits

Managing Services

# View logs
docker-compose logs -f graph-node

# Stop services
docker-compose stop

# Stop and remove containers
docker-compose down

# Reset all data (WARNING: deletes databases)
docker-compose down -v
rm -rf data/

# Restart a single service
docker-compose restart graph-node

# Update to latest image
docker-compose pull
docker-compose up -d

Next Steps

• Environment Variables - Complete reference of all configuration options
• Configuration Overview - Advanced multi-database and multi-chain setup
• Building from Source - Compile Graph Node yourself