Skip to main content
This quickstart guide is designed for subgraph developers who want to run Graph Node locally to test their subgraphs during development. If you’re looking to contribute to Graph Node itself, see the Installation page.

​
What You’ll Build

By the end of this guide, you’ll have:
  • A fully functional Graph Node instance running locally
  • IPFS and PostgreSQL configured and ready
  • The ability to deploy and query subgraphs

​
Prerequisites

Before you begin, ensure you have:
  • Docker and Docker Compose installed (Get Docker)
  • An Ethereum node or RPC endpoint (e.g., Infura, Alchemy, or a local node)
  • graph-cli for deploying subgraphs: npm install -g @graphprotocol/graph-cli
For local testing, you can use Ganache or Hardhat as your Ethereum node.

​
Quick Setup with Docker Compose

1

Clone Graph Node repository

First, clone the Graph Node repository to get the Docker Compose configuration:
git clone https://github.com/graphprotocol/graph-node.git
cd graph-node/docker
2

Configure your Ethereum connection

Edit docker-compose.yml to point to your Ethereum node. By default, it uses:
ethernet: 'mainnet:http://host.docker.internal:8545'
Common configurations:
ethernet: 'mainnet:http://host.docker.internal:8545'
The format is NETWORK_NAME:RPC_URL. You can specify multiple networks separated by commas.
3

Start the services

Launch Graph Node along with IPFS and PostgreSQL:
docker-compose up
You should see output indicating all three services are starting. The first run will download Docker images (~2-3 GB).
Add -d flag to run in detached mode: docker-compose up -d
4

Verify the setup

Once all services are running, verify your Graph Node is accessible:
curl http://localhost:8000/
You should see the GraphiQL interface when you open http://localhost:8000/ in your browser.

​
Service Endpoints

Your Graph Node setup exposes the following endpoints:

GraphQL HTTP

http://localhost:8000/subgraphs/name/<subgraph-name>Query your deployed subgraphs

GraphQL WebSocket

ws://localhost:8001/subgraphs/name/<subgraph-name>Subscribe to real-time updates

GraphiQL Interface

http://localhost:8000/Interactive query explorer

Admin API

http://localhost:8020/Manage deployments

IPFS API

http://127.0.0.1:5001Access IPFS directly

PostgreSQL

postgresql://graph-node:let-me-in@localhost:5432/graph-nodeDirect database access

​
Deploy Your First Subgraph

Now that Graph Node is running, let’s deploy a subgraph:
1

Create or clone a subgraph

If you don’t have a subgraph yet, you can create one:
graph init --product subgraph-studio my-subgraph
cd my-subgraph
2

Build your subgraph

graph codegen
graph build
3

Create the subgraph locally

graph create my-subgraph --node http://localhost:8020
4

Deploy the subgraph

graph deploy my-subgraph --ipfs http://localhost:5001 --node http://localhost:8020
You’ll be prompted for a version label. Enter something like v0.0.1.
5

Query your subgraph

Once deployed and synced, query your subgraph at:
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "{ _meta { block { number } } }"}' \
  http://localhost:8000/subgraphs/name/my-subgraph
Or visit http://localhost:8000/subgraphs/name/my-subgraph in GraphiQL.

​
Data Persistence

Docker Compose creates persistent data directories:
  • IPFS data: ./data/ipfs
  • PostgreSQL data: ./data/postgres
These directories persist your data across container restarts. To reset your environment: 
docker-compose down -v
rm -rf data/
Deleting these directories will remove all deployed subgraphs and indexed data.

​
Monitoring and Logs

​
View logs

# All services
docker-compose logs -f

# Graph Node only
docker-compose logs -f graph-node

# Last 100 lines
docker-compose logs --tail=100 graph-node

​
Check service status

docker-compose ps

​
Adjust log verbosity

Edit the GRAPH_LOG environment variable in docker-compose.yml: 
environment:
  GRAPH_LOG: debug  # Options: error, warn, info, debug, trace

​
Running on Apple Silicon (M1/M2)

Graph Node doesn’t currently provide native ARM64 images. M1/M2 Macs may experience memory issues.
To build a native image for Apple Silicon:
1

Increase Docker memory

Open Docker Desktop → Resources → Advanced → Memory and increase to at least 8GB.
2

Remove the official image

docker rmi graphprotocol/graph-node:latest
3

Build locally

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

Start services

cd docker
docker-compose up

​
Common Configuration

​
Multiple Ethereum networks

Edit docker-compose.yml to support multiple networks: 
environment:
  ethernet: 'mainnet:https://mainnet.infura.io/v3/YOUR_KEY,sepolia:https://sepolia.infura.io/v3/YOUR_KEY'

​
Archive node features

If your RPC endpoint is an archive node with tracing support: 
european: 'mainnet:archive,traces:https://your-archive-node.com'

​
Connection pool size

For better performance under load: 
environment:
  postgres_host: postgres
  postgres_user: graph-node
  postgres_pass: let-me-in
  postgres_db: graph-node
  STORE_CONNECTION_POOL_SIZE: 25  # Default is 10

​
Troubleshooting

Symptoms: Logs show connection errors to Ethereum RPCSolutions:
  • Verify your RPC URL is correct
  • Check that host.docker.internal resolves (macOS/Windows only)
  • For Linux, use --network="host" or your machine’s IP address
  • Ensure your Ethereum node is running and accessible
Symptoms: Container killed with exit code 137Solutions:
  • Increase Docker Desktop memory limit (8GB minimum)
  • Build a native ARM64 image using the steps above
  • Consider using a cloud Ethereum provider instead of local node
Symptoms: could not connect to server: Connection refusedSolutions:
  • Ensure PostgreSQL container is running: docker-compose ps
  • Check PostgreSQL logs: docker-compose logs postgres
  • Verify port 5432 isn’t in use by another process
  • Reset containers: docker-compose down && docker-compose up
Symptoms: ipfs.cat timeouts in logsSolutions:
  • Increase IPFS timeout: Add GRAPH_IPFS_TIMEOUT: 120 to environment
  • Check IPFS is running: curl http://localhost:5001/api/v0/version
  • Restart IPFS container: docker-compose restart ipfs
Symptoms: Deployment command hangs or failsSolutions:
  • Verify admin endpoint is accessible: curl http://localhost:8020/
  • Ensure IPFS is running: docker-compose ps ipfs
  • Check Graph Node logs: docker-compose logs graph-node
  • Try recreating: graph remove <subgraph-name> --node http://localhost:8020

​
Next Steps

Installation

Learn about running Graph Node from source

Configuration

Advanced configuration with TOML files

Subgraph Development

Official subgraph development guide

Environment Variables

Fine-tune Graph Node behavior

​
Running Without Docker Compose

If you already have IPFS and PostgreSQL running, you can run Graph Node directly: 
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> \
  graphprotocol/graph-node:latest
See the Installation page for running from source.

Build docs developers (and LLMs) love

Get started for freeTalk to us