Building from Source

Building Graph Node from source is typically needed for contributors or developers who want to modify Graph Node itself. For subgraph development, using Docker is recommended.

Prerequisites

Ensure the following are installed on your system:

toolchain

required

Latest stable Rust compiler and toolchainInstall via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup install stable

database

required

PostgreSQL 12 or higher

macOS: Postgres.app (recommended)
Linux: Use your distribution’s package manager
Windows: PostgreSQL Downloads

service

required

IPFS daemon (Kubo)Install IPFS

build-tool

required

Protocol Buffers compiler

macOS: brew install protobuf
Linux: apt-get install protobuf-compiler or dnf install protobuf-compiler
Manual: Installing Protobuf

service

required

Access to an Ethereum RPC endpointOptions:

Local node (Geth, Erigon, Nethermind)
Provider service (Infura, Alchemy, QuickNode)

Setup Instructions

Clone the Repository

Clone Graph Node from GitHub:

git clone https://github.com/graphprotocol/graph-node.git
cd graph-node

Install Rust Components

Ensure all required Rust components are installed:

rustup install stable
rustup default stable

The graph-node codebase assumes the latest available stable compiler is used.

Set Up PostgreSQL

Create a database and configure it for Graph Node.

Create Database and User

The superuser name depends on your installation (usually postgres or your username):

psql -U <SUPERUSER> <<EOF
create user graph with password '<password>';
create database "graph-node" with owner=graph template=template0 encoding='UTF8' locale='C';
create extension pg_trgm;
create extension btree_gist;
create extension postgres_fdw;
grant usage on foreign data wrapper postgres_fdw to graph;
EOF

Required PostgreSQL extensions:

pg_trgm: Trigram matching for text search
btree_gist: B-tree indexing support
postgres_fdw: Foreign data wrapper for multi-database setups

Set Connection String

Set the POSTGRES_URL environment variable and save it (e.g., in ~/.bashrc or ~/.zshrc):

export POSTGRES_URL=postgresql://graph:<password>@localhost:5432/graph-node

Verify the connection:

psql $POSTGRES_URL

Start IPFS

Initialize and start the IPFS daemon:

ipfs init
ipfs daemon

IPFS should be accessible at 127.0.0.1:5001.

Build Graph Node

Build the Graph Node binary in release mode:

cargo build --release -p graph-node

This compiles the graph-node binary to target/release/graph-node.

Build Time and Resources

Initial builds can take 15-30 minutes depending on your system. Ensure you have:

At least 8GB RAM
10GB free disk space
Good internet connection for downloading dependencies

Run Graph Node

Start Graph Node with the required configuration:

export GRAPH_LOG=debug
cargo run -p graph-node --release -- \
  --postgres-url $POSTGRES_URL \
  --ethereum-rpc NETWORK_NAME:[CAPABILITIES]:URL \
  --ipfs 127.0.0.1:5001

Ethereum RPC Format

The --ethereum-rpc argument format is:

NETWORK_NAME:[CAPABILITIES]:URL

Examples:

# Mainnet with archive and trace support
--ethereum-rpc mainnet:archive,traces:https://mainnet.infura.io/v3/YOUR-KEY

# Multiple networks
--ethereum-rpc mainnet:archive:https://eth-mainnet.g.alchemy.com/v2/KEY \
               sepolia:https://sepolia.infura.io/v3/KEY

# Local node
--ethereum-rpc mainnet:http://localhost:8545

Common Capabilities:

archive: Full historical state available
traces: Supports debug_traceBlockByNumber for call tracing

Verify Graph Node is Running

Graph Node prints the ports it’s listening on when it starts. By default:

GraphQL HTTP: http://localhost:8000
GraphQL WebSocket: ws://localhost:8001
JSON-RPC Admin: http://localhost:8020
Indexing Status: http://localhost:8030

Test the GraphQL endpoint:

curl http://localhost:8000

Deploying a Subgraph

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

Install Graph CLI

npm install -g @graphprotocol/graph-cli
# or
yarn global add @graphprotocol/graph-cli

Create a Subgraph

graph init --studio my-subgraph
cd my-subgraph

Generate Code and Build

graph codegen
graph build

Create and Deploy

# Create the subgraph on your local node
graph create --node http://localhost:8020/ my-subgraph

# Deploy to your local node
graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 my-subgraph

Query the Subgraph

Once deployed, query at:

http://localhost:8000/subgraphs/name/my-subgraph

Or use GraphiQL:

http://localhost:8000/subgraphs/name/my-subgraph/graphql

Development Workflow

Running Tests

# Run all tests
cargo test --workspace

# Run tests for a specific package
cargo test -p graph-store-postgres

# Run a specific test
cargo test test_name

Code Quality

# Format code (required before commits)
cargo fmt --all

# Check for errors without building
cargo check

# Run linter
cargo clippy --all --all-targets

Building Specific Components

# Build only graph-node binary
cargo build --release -p graph-node

# Build graphman CLI tool
cargo build --release -p graph-node --bin graphman

# Build with debug symbols
cargo build -p graph-node

Command Line Arguments

string

required

PostgreSQL connection stringFormat: postgresql://user:password@host:port/database

string

required

Ethereum network configurationFormat: NETWORK:[CAPABILITIES]:URLCan be specified multiple times for multiple networks.

string

required

IPFS node addressDefault: 127.0.0.1:5001

string

Unique identifier for this node (for multi-node setups)Default: default

string

Path to TOML configuration file for advanced setupsMutually exclusive with --postgres-url and --ethereum-rpc

boolean

Enable debug logging

Advanced Configuration

For complex deployments, use a TOML configuration file instead of command-line arguments:

cargo run -p graph-node --release -- \
  --config /path/to/config.toml \
  --node-id index-node-1

This is useful for:

Multiple PostgreSQL databases (sharding)
Multiple blockchain networks
Advanced indexing and query node separation
Custom deployment rules

Environment Variables

Many aspects of Graph Node can be configured via environment variables:

# Logging
export GRAPH_LOG=info
export RUST_LOG=info

# Performance tuning
export GRAPH_ETHEREUM_TARGET_TRIGGERS_PER_BLOCK_RANGE=100
export ETHEREUM_POLLING_INTERVAL=500
export GRAPH_ENTITY_CACHE_SIZE=10000

# GraphQL configuration
export GRAPH_GRAPHQL_MAX_COMPLEXITY=1000000
export GRAPH_GRAPHQL_MAX_FIRST=1000

# Run Graph Node
cargo run -p graph-node --release -- \
  --postgres-url $POSTGRES_URL \
  --ethereum-rpc mainnet:http://localhost:8545 \
  --ipfs 127.0.0.1:5001

System Requirements

Minimum Requirements

CPU: 4 cores
RAM: 8GB
Disk: 50GB SSD (more for indexing mainnet)
Network: Stable broadband connection

Recommended for Production

CPU: 16+ cores
RAM: 32GB+
Disk: 500GB+ NVMe SSD
Network: 1Gbps connection
PostgreSQL: Dedicated database server with tuning

Troubleshooting

Compilation errors

Ensure you have the latest stable Rust:

rustup update stable
rustup default stable

Install system dependencies:

# Ubuntu/Debian
sudo apt-get install build-essential pkg-config libssl-dev libpq-dev

# macOS
brew install postgresql openssl pkg-config

PostgreSQL connection failures

Verify the connection string:

psql $POSTGRES_URL -c "SELECT version();"

Check PostgreSQL is running:

pg_isready -h localhost -p 5432

Ensure required extensions are installed:

\dx

IPFS connection errors

Verify IPFS is running:

ipfs id
curl http://127.0.0.1:5001/api/v0/version

Check IPFS configuration:

ipfs config show

Out of memory during compilation

Reduce parallel compilation jobs:

cargo build --release -p graph-node -j 2

Or build without release optimizations initially:

cargo build -p graph-node

Ethereum RPC errors

Test your Ethereum endpoint:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  YOUR_RPC_URL

Ensure your RPC provider supports required methods:

eth_getLogs
eth_getBlockByNumber
eth_call
debug_traceBlockByNumber (for traces)

GraphMan CLI Tool

Graph Node includes graphman, a CLI tool for database management:

# Build graphman
cargo build --release -p graph-node --bin graphman

# Run graphman
./target/release/graphman --help

# Common operations
./target/release/graphman info <deployment-id>
./target/release/graphman rewind <deployment-id> <block-number>
./target/release/graphman remove <deployment-id>

Next Steps

Environment Variables - Tune performance and behavior
Configuration Overview - Advanced TOML configuration
Docker Setup - Alternative deployment method
Contributing Guide - Contribute to Graph Node

Get Started

Core Concepts

Running Graph Node

Deployment

Advanced Configuration

Operations

Building from Source

Prerequisites

Setup Instructions

Deploying a Subgraph

Development Workflow

Running Tests

Code Quality

Building Specific Components

Command Line Arguments

Advanced Configuration

Environment Variables

System Requirements

Minimum Requirements

Recommended for Production

Troubleshooting

GraphMan CLI Tool

Next Steps

​Prerequisites

​Setup Instructions

​Deploying a Subgraph

​Development Workflow

​Running Tests

​Code Quality

​Building Specific Components

​Command Line Arguments

​Advanced Configuration

​Environment Variables

​System Requirements

​Minimum Requirements

​Recommended for Production

​Troubleshooting

​GraphMan CLI Tool

​Next Steps

Prerequisites

Setup Instructions

Deploying a Subgraph

Development Workflow

Running Tests

Code Quality

Building Specific Components

Command Line Arguments

Advanced Configuration

Environment Variables

System Requirements

Minimum Requirements

Recommended for Production

Troubleshooting

GraphMan CLI Tool

Next Steps