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

# Quickstart

> Get Graph Node running locally in minutes with Docker. Perfect for testing subgraphs during development.

<Note>
  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](/installation) page.
</Note>

## 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](https://docs.docker.com/get-docker/))
* **An Ethereum node** or RPC endpoint (e.g., [Infura](https://infura.io/), [Alchemy](https://www.alchemy.com/), or a local node)
* **graph-cli** for deploying subgraphs: `npm install -g @graphprotocol/graph-cli`

<Tip>
  For local testing, you can use [Ganache](https://trufflesuite.com/ganache/) or [Hardhat](https://hardhat.org/) as your Ethereum node.
</Tip>

## Quick Setup with Docker Compose

<Steps>
  <Step title="Clone Graph Node repository">
    First, clone the Graph Node repository to get the Docker Compose configuration:

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

  <Step title="Configure your Ethereum connection">
    Edit `docker-compose.yml` to point to your Ethereum node. By default, it uses:

    ```yaml theme={null}
    ethernet: 'mainnet:http://host.docker.internal:8545'
    ```

    **Common configurations:**

    <CodeGroup>
      ```yaml Local Ethereum Node theme={null}
      ethernet: 'mainnet:http://host.docker.internal:8545'
      ```

      ```yaml Infura theme={null}
      ethernet: 'mainnet:https://mainnet.infura.io/v3/YOUR_PROJECT_ID'
      ```

      ```yaml Alchemy theme={null}
      ethernet: 'mainnet:https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY'
      ```

      ```yaml Sepolia Testnet theme={null}
      ethernet: 'sepolia:https://sepolia.infura.io/v3/YOUR_PROJECT_ID'
      ```

      ```yaml Multiple Networks theme={null}
      ethernet: 'mainnet:https://...,sepolia:https://...'
      ```
    </CodeGroup>

    <Note>
      The format is `NETWORK_NAME:RPC_URL`. You can specify multiple networks separated by commas.
    </Note>
  </Step>

  <Step title="Start the services">
    Launch Graph Node along with IPFS and PostgreSQL:

    ```bash theme={null}
    docker-compose up
    ```

    You should see output indicating all three services are starting. The first run will download Docker images (\~2-3 GB).

    <Tip>
      Add `-d` flag to run in detached mode: `docker-compose up -d`
    </Tip>
  </Step>

  <Step title="Verify the setup">
    Once all services are running, verify your Graph Node is accessible:

    ```bash theme={null}
    curl http://localhost:8000/
    ```

    You should see the GraphiQL interface when you open `http://localhost:8000/` in your browser.
  </Step>
</Steps>

## Service Endpoints

Your Graph Node setup exposes the following endpoints:

<CardGroup cols={2}>
  <Card title="GraphQL HTTP" icon="globe">
    `http://localhost:8000/subgraphs/name/<subgraph-name>`

    Query your deployed subgraphs
  </Card>

  <Card title="GraphQL WebSocket" icon="plug">
    `ws://localhost:8001/subgraphs/name/<subgraph-name>`

    Subscribe to real-time updates
  </Card>

  <Card title="GraphiQL Interface" icon="browser">
    `http://localhost:8000/`

    Interactive query explorer
  </Card>

  <Card title="Admin API" icon="gear">
    `http://localhost:8020/`

    Manage deployments
  </Card>

  <Card title="IPFS API" icon="database">
    `http://127.0.0.1:5001`

    Access IPFS directly
  </Card>

  <Card title="PostgreSQL" icon="table">
    `postgresql://graph-node:let-me-in@localhost:5432/graph-node`

    Direct database access
  </Card>
</CardGroup>

## Deploy Your First Subgraph

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

<Steps>
  <Step title="Create or clone a subgraph">
    If you don't have a subgraph yet, you can create one:

    ```bash theme={null}
    graph init --product subgraph-studio my-subgraph
    cd my-subgraph
    ```
  </Step>

  <Step title="Build your subgraph">
    ```bash theme={null}
    graph codegen
    graph build
    ```
  </Step>

  <Step title="Create the subgraph locally">
    ```bash theme={null}
    graph create my-subgraph --node http://localhost:8020
    ```
  </Step>

  <Step title="Deploy the subgraph">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="Query your subgraph">
    Once deployed and synced, query your subgraph at:

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

## 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:

```bash theme={null}
docker-compose down -v
rm -rf data/
```

<Warning>
  Deleting these directories will remove all deployed subgraphs and indexed data.
</Warning>

## Monitoring and Logs

### View logs

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

```bash theme={null}
docker-compose ps
```

### Adjust log verbosity

Edit the `GRAPH_LOG` environment variable in `docker-compose.yml`:

```yaml theme={null}
environment:
  GRAPH_LOG: debug  # Options: error, warn, info, debug, trace
```

## Running on Apple Silicon (M1/M2)

<Warning>
  Graph Node doesn't currently provide native ARM64 images. M1/M2 Macs may experience memory issues.
</Warning>

To build a native image for Apple Silicon:

<Steps>
  <Step title="Increase Docker memory">
    Open Docker Desktop → Resources → Advanced → Memory and increase to at least 8GB.
  </Step>

  <Step title="Remove the official image">
    ```bash theme={null}
    docker rmi graphprotocol/graph-node:latest
    ```
  </Step>

  <Step title="Build locally">
    ```bash theme={null}
    cd graph-node
    ./docker/build.sh
    docker tag graph-node graphprotocol/graph-node:latest
    ```
  </Step>

  <Step title="Start services">
    ```bash theme={null}
    cd docker
    docker-compose up
    ```
  </Step>
</Steps>

## Common Configuration

### Multiple Ethereum networks

Edit `docker-compose.yml` to support multiple networks:

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

```yaml theme={null}
european: 'mainnet:archive,traces:https://your-archive-node.com'
```

### Connection pool size

For better performance under load:

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

<AccordionGroup>
  <Accordion title="Graph Node can't connect to Ethereum node">
    **Symptoms**: Logs show connection errors to Ethereum RPC

    **Solutions**:

    * 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
  </Accordion>

  <Accordion title="Out of memory errors on M1 Macs">
    **Symptoms**: Container killed with exit code 137

    **Solutions**:

    * 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
  </Accordion>

  <Accordion title="Postgres connection refused">
    **Symptoms**: `could not connect to server: Connection refused`

    **Solutions**:

    * 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`
  </Accordion>

  <Accordion title="IPFS timeout errors">
    **Symptoms**: `ipfs.cat` timeouts in logs

    **Solutions**:

    * 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`
  </Accordion>

  <Accordion title="Subgraph deployment fails">
    **Symptoms**: Deployment command hangs or fails

    **Solutions**:

    * 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`
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Learn about running Graph Node from source
  </Card>

  <Card title="Configuration" icon="sliders" href="/running/configuration">
    Advanced configuration with TOML files
  </Card>

  <Card title="Subgraph Development" icon="book" href="https://thegraph.com/docs/en/developing/creating-a-subgraph/">
    Official subgraph development guide
  </Card>

  <Card title="Environment Variables" icon="gear" href="/running/environment-variables">
    Fine-tune Graph Node behavior
  </Card>
</CardGroup>

## Running Without Docker Compose

If you already have IPFS and PostgreSQL running, you can run Graph Node directly:

```bash theme={null}
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](/installation) page for running from source.