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

# Docker Setup

> Complete guide to running Graph Node with Docker and Docker Compose

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](https://docs.docker.com/get-docker/)
* **Docker Compose**: [Install Docker Compose](https://docs.docker.com/compose/install/)
* **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.

<Steps>
  <Step title="Clone the Repository">
    First, get the Graph Node repository:

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

  <Step title="Configure Ethereum Connection">
    Edit `docker-compose.yml` to set your Ethereum node endpoint. By default, it connects to `mainnet:http://host.docker.internal:8545`.

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

    <Accordion title="Example: Multiple Networks">
      ```yaml theme={null}
      environment:
        ethereum: 'mainnet:https://mainnet.infura.io/v3/PROJECT-ID,sepolia:https://sepolia.infura.io/v3/PROJECT-ID'
      ```
    </Accordion>
  </Step>

  <Step title="Start the Services">
    Launch all services (Graph Node, PostgreSQL, IPFS):

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

    For background execution:

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

    This creates persistent data directories:

    * `./data/ipfs` - IPFS data
    * `./data/postgres` - PostgreSQL database
  </Step>

  <Step title="Verify Services">
    Check that all services are running:

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

    Access the endpoints:

    * **GraphiQL Interface**: [http://localhost:8000](http://localhost:8000)
    * **HTTP Queries**: `http://localhost:8000/subgraphs/name/<subgraph-name>`
    * **WebSocket**: `ws://localhost:8001/subgraphs/name/<subgraph-name>`
    * **Admin API**: [http://localhost:8020](http://localhost:8020)
    * **IPFS**: [http://127.0.0.1:5001](http://127.0.0.1:5001)
  </Step>
</Steps>

## Docker Compose Configuration

The complete `docker-compose.yml` configuration:

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

<ParamField path="8000" type="HTTP">
  GraphQL HTTP server for querying subgraphs
</ParamField>

<ParamField path="8001" type="WebSocket">
  GraphQL WebSocket server for subscriptions
</ParamField>

<ParamField path="8020" type="JSON-RPC">
  Admin API for managing subgraphs
</ParamField>

<ParamField path="8030" type="HTTP">
  Indexing status and metrics
</ParamField>

<ParamField path="8040" type="HTTP">
  Prometheus metrics endpoint
</ParamField>

## Running with Existing Infrastructure

If you already have PostgreSQL and IPFS running, use the standalone Docker image:

```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> \
  -p 8000:8000 \
  -p 8001:8001 \
  -p 8020:8020 \
  -p 8030:8030 \
  graphprotocol/graph-node:latest
```

### Example: Connecting to External Services

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

<ParamField path="postgres_host" type="string" required>
  PostgreSQL server hostname
</ParamField>

<ParamField path="postgres_port" type="number" default="5432">
  PostgreSQL server port
</ParamField>

<ParamField path="postgres_user" type="string" required>
  Database username
</ParamField>

<ParamField path="postgres_pass" type="string" required>
  Database password
</ParamField>

<ParamField path="postgres_db" type="string" required>
  Database name
</ParamField>

<ParamField path="postgres_args" type="string" default="sslmode=prefer">
  Additional PostgreSQL connection arguments
</ParamField>

<ParamField path="ipfs" type="string" required>
  IPFS node address (e.g., `ipfs:5001` or `127.0.0.1:5001`)
</ParamField>

<ParamField path="ethereum" type="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`
</ParamField>

<ParamField path="node_role" type="string" default="combined-node">
  Node role: `combined-node`, `index-node`, or `query-node`
</ParamField>

<ParamField path="node_id" type="string" default="default">
  Unique identifier for this node
</ParamField>

<ParamField path="GRAPH_LOG" type="string" default="info">
  Log level: `error`, `warn`, `info`, `debug`, `trace`
</ParamField>

<ParamField path="GRAPH_NODE_CONFIG" type="string">
  Path to advanced TOML configuration file (optional)
</ParamField>

<ParamField path="disable_core_dumps" type="boolean">
  Set to any value to disable core dumps (useful for query nodes with large caches)
</ParamField>

## Apple Silicon (M1/M2) Support

Graph Node doesn't provide native ARM64 images. On Apple Silicon Macs, build locally:

<Steps>
  <Step title="Increase Docker Memory">
    Open Docker Desktop → Settings → Resources → Advanced → Memory

    Set to at least 8GB to avoid build failures.
  </Step>

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

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

  <Step title="Run Docker Compose">
    ```bash theme={null}
    cd docker
    docker-compose up
    ```
  </Step>
</Steps>

## Using Configuration Files

For advanced setups (multiple databases, custom chain configs), use a TOML configuration file:

```bash theme={null}
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](/running/configuration) for details on the TOML format.

## Deploying Subgraphs

Once Graph Node is running, deploy subgraphs using [Graph CLI](https://thegraph.com/docs/en/subgraphs/developing/introduction/):

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

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

  <Step title="Build and Deploy">
    ```bash theme={null}
    graph codegen
    graph build
    graph create --node http://localhost:8020/ my-subgraph
    graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 my-subgraph
    ```
  </Step>
</Steps>

## Troubleshooting

<Accordion title="Connection refused to Ethereum node">
  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:

  ```bash theme={null}
  ethereum: 'mainnet:http://192.168.1.100:8545'
  ```
</Accordion>

<Accordion title="PostgreSQL connection errors">
  Ensure PostgreSQL allows connections from Docker containers. Check `pg_hba.conf` and verify the container can reach the host:

  ```bash theme={null}
  docker-compose exec graph-node nc -zv postgres 5432
  ```
</Accordion>

<Accordion title="IPFS timeout errors">
  Verify IPFS is accessible:

  ```bash theme={null}
  curl http://localhost:5001/api/v0/version
  ```

  If using external IPFS, ensure it's publicly accessible or on the same network.
</Accordion>

<Accordion title="Out of memory errors">
  Increase Docker's memory limit:

  * Docker Desktop: Settings → Resources → Advanced → Memory (set to 8GB+)
  * Linux: Edit `/etc/docker/daemon.json` to increase memory limits
</Accordion>

## Managing Services

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

* [Environment Variables](/running/environment-variables) - Complete reference of all configuration options
* [Configuration Overview](/running/configuration) - Advanced multi-database and multi-chain setup
* [Building from Source](/running/from-source) - Compile Graph Node yourself