> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/graphprotocol/graph-node/llms.txt
> Use this file to discover all available pages before exploring further.

# Building from Source

> Build and run Graph Node from source code for development and contributions

Building Graph Node from source is typically needed for contributors or developers who want to modify Graph Node itself. For subgraph development, using [Docker](/running/docker-setup) is recommended.

## Prerequisites

Ensure the following are installed on your system:

<ParamField path="Rust" type="toolchain" required>
  Latest stable Rust compiler and toolchain

  Install via [rustup](https://rustup.rs/):

  ```bash theme={null}
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  rustup install stable
  ```
</ParamField>

<ParamField path="PostgreSQL" type="database" required>
  PostgreSQL 12 or higher

  * **macOS**: [Postgres.app](https://postgresapp.com/) (recommended)
  * **Linux**: Use your distribution's package manager
  * **Windows**: [PostgreSQL Downloads](https://www.postgresql.org/download/)
</ParamField>

<ParamField path="IPFS" type="service" required>
  IPFS daemon (Kubo)

  [Install IPFS](https://docs.ipfs.tech/install/)
</ParamField>

<ParamField path="Protobuf Compiler" type="build-tool" required>
  Protocol Buffers compiler

  * **macOS**: `brew install protobuf`
  * **Linux**: `apt-get install protobuf-compiler` or `dnf install protobuf-compiler`
  * **Manual**: [Installing Protobuf](https://grpc.io/docs/protoc-installation/)
</ParamField>

<ParamField path="Ethereum Node" type="service" required>
  Access to an Ethereum RPC endpoint

  Options:

  * Local node (Geth, Erigon, Nethermind)
  * Provider service (Infura, Alchemy, QuickNode)
</ParamField>

## Setup Instructions

<Steps>
  <Step title="Clone the Repository">
    Clone Graph Node from GitHub:

    ```bash theme={null}
    git clone https://github.com/graphprotocol/graph-node.git
    cd graph-node
    ```
  </Step>

  <Step title="Install Rust Components">
    Ensure all required Rust components are installed:

    ```bash theme={null}
    rustup install stable
    rustup default stable
    ```

    The `graph-node` codebase assumes the latest available `stable` compiler is used.
  </Step>

  <Step title="Set Up PostgreSQL">
    Create a database and configure it for Graph Node.

    <Accordion title="Create Database and User">
      The superuser name depends on your installation (usually `postgres` or your username):

      ```bash theme={null}
      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
    </Accordion>

    <Accordion title="Set Connection String">
      Set the `POSTGRES_URL` environment variable and save it (e.g., in `~/.bashrc` or `~/.zshrc`):

      ```bash theme={null}
      export POSTGRES_URL=postgresql://graph:<password>@localhost:5432/graph-node
      ```

      Verify the connection:

      ```bash theme={null}
      psql $POSTGRES_URL
      ```
    </Accordion>
  </Step>

  <Step title="Start IPFS">
    Initialize and start the IPFS daemon:

    ```bash theme={null}
    ipfs init
    ipfs daemon
    ```

    IPFS should be accessible at `127.0.0.1:5001`.
  </Step>

  <Step title="Build Graph Node">
    Build the Graph Node binary in release mode:

    ```bash theme={null}
    cargo build --release -p graph-node
    ```

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

    <Accordion title="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
    </Accordion>
  </Step>

  <Step title="Run Graph Node">
    Start Graph Node with the required configuration:

    ```bash theme={null}
    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
    ```

    <Accordion title="Ethereum RPC Format">
      The `--ethereum-rpc` argument format is:

      ```
      NETWORK_NAME:[CAPABILITIES]:URL
      ```

      **Examples:**

      ```bash theme={null}
      # 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
    </Accordion>
  </Step>

  <Step title="Verify Graph Node is Running">
    Graph Node prints the ports it's listening on when it starts. By default:

    * **GraphQL HTTP**: [http://localhost:8000](http://localhost:8000)
    * **GraphQL WebSocket**: ws\://localhost:8001
    * **JSON-RPC Admin**: [http://localhost:8020](http://localhost:8020)
    * **Indexing Status**: [http://localhost:8030](http://localhost:8030)

    Test the GraphQL endpoint:

    ```bash theme={null}
    curl http://localhost:8000
    ```
  </Step>
</Steps>

## Deploying a Subgraph

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

<Steps>
  <Step title="Install Graph CLI">
    ```bash theme={null}
    npm install -g @graphprotocol/graph-cli
    # or
    yarn global add @graphprotocol/graph-cli
    ```
  </Step>

  <Step title="Create a Subgraph">
    ```bash theme={null}
    graph init --studio my-subgraph
    cd my-subgraph
    ```
  </Step>

  <Step title="Generate Code and Build">
    ```bash theme={null}
    graph codegen
    graph build
    ```
  </Step>

  <Step title="Create and Deploy">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="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
    ```
  </Step>
</Steps>

## Development Workflow

### Running Tests

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

<ParamField path="--postgres-url" type="string" required>
  PostgreSQL connection string

  Format: `postgresql://user:password@host:port/database`
</ParamField>

<ParamField path="--ethereum-rpc" type="string" required>
  Ethereum network configuration

  Format: `NETWORK:[CAPABILITIES]:URL`

  Can be specified multiple times for multiple networks.
</ParamField>

<ParamField path="--ipfs" type="string" required>
  IPFS node address

  Default: `127.0.0.1:5001`
</ParamField>

<ParamField path="--node-id" type="string">
  Unique identifier for this node (for multi-node setups)

  Default: `default`
</ParamField>

<ParamField path="--config" type="string">
  Path to TOML configuration file for advanced setups

  Mutually exclusive with `--postgres-url` and `--ethereum-rpc`
</ParamField>

<ParamField path="--debug" type="boolean">
  Enable debug logging
</ParamField>

## Advanced Configuration

For complex deployments, use a [TOML configuration file](/running/configuration) instead of command-line arguments:

```bash theme={null}
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](/running/environment-variables):

```bash theme={null}
# 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

<Accordion title="Compilation errors">
  Ensure you have the latest stable Rust:

  ```bash theme={null}
  rustup update stable
  rustup default stable
  ```

  Install system dependencies:

  ```bash theme={null}
  # Ubuntu/Debian
  sudo apt-get install build-essential pkg-config libssl-dev libpq-dev

  # macOS
  brew install postgresql openssl pkg-config
  ```
</Accordion>

<Accordion title="PostgreSQL connection failures">
  Verify the connection string:

  ```bash theme={null}
  psql $POSTGRES_URL -c "SELECT version();"
  ```

  Check PostgreSQL is running:

  ```bash theme={null}
  pg_isready -h localhost -p 5432
  ```

  Ensure required extensions are installed:

  ```sql theme={null}
  \dx
  ```
</Accordion>

<Accordion title="IPFS connection errors">
  Verify IPFS is running:

  ```bash theme={null}
  ipfs id
  curl http://127.0.0.1:5001/api/v0/version
  ```

  Check IPFS configuration:

  ```bash theme={null}
  ipfs config show
  ```
</Accordion>

<Accordion title="Out of memory during compilation">
  Reduce parallel compilation jobs:

  ```bash theme={null}
  cargo build --release -p graph-node -j 2
  ```

  Or build without release optimizations initially:

  ```bash theme={null}
  cargo build -p graph-node
  ```
</Accordion>

<Accordion title="Ethereum RPC errors">
  Test your Ethereum endpoint:

  ```bash theme={null}
  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)
</Accordion>

## GraphMan CLI Tool

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

```bash theme={null}
# 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](/running/environment-variables) - Tune performance and behavior
* [Configuration Overview](/running/configuration) - Advanced TOML configuration
* [Docker Setup](/running/docker-setup) - Alternative deployment method
* [Contributing Guide](https://github.com/graphprotocol/graph-node/blob/master/CONTRIBUTING.md) - Contribute to Graph Node