Skip to main content
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://...
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:

​
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 → MemorySet 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

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'
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
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.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us