Getting started for the local development

The Steps of Deploying a Subgraph Locally.

Before we start, let’s have a quick look at the steps covered in this guide

  • 1. Setting up Ganache CLI
  • 2. Starting Graph Node locally
  • 3. Initializing new subgraph
  • 4. Deploying sample smart contract to Ganache
  • 5. Deploying subgraph to local Graph Node
  • 6. Using subgraph in a dApp built with React

1. Setting up Ganache CLI.

Set up your terminal and run the following two commands within it to install Ganache and Truffle globally:

Copy to Clipboard

Wait for it to finish installing. Once it’s done, run the following command in the same terminal:

Copy to Clipboard

What this does is to create a total of 10 test accounts for you that have some ETH on all of them.

Ganache binds by default to, making it only accessible from the host machine it is running on. For this reason, it is necessary to add -h within the command to make it assessable from within Docker.

Please note: When using Ganache for subgraph testing, it may appear The Graph Node is not running handlers. Make sure to fully understand how Ganache is running tests to avoid unexpected consequences.

  • While running tests, Ganache takes snapshots of the blockchain and reverts it to a clean deployment of the contract. This causes of The Graph Node to seize.
  • If you continue deploying new instances, the contract addresses will differ from the deployer contract address. As a consequence, there is not one single address you can add to the subgraph.yaml manifest.

2. Starting Graph Node locally.

A) Cloning The Graph Node

Open another terminal and clone The Graph Node with the following command:

Copy to Clipboard

B) Accessing Docker directory of The Graph Node

Continue in the process by accessing The Graph Node’s Docker directory:

Copy to Clipboard

C) Replacing host IP (Linux users only)

(This step is for Linux users only): Linux does not support the host.docker.internal alias for the host machine that The Graph Node Docker Compose uses. Run the following command from the Docker directory to replace the alias with the host IP address. What this does is that the host IP address will be automatically written into docker-compose.yml.

Copy to Clipboard

D) Starting the local Graph Node

You can now start the local Graph Node to connect to Ganache on your host. To do so, run the following command:

Copy to Clipboard

3. Initializing new subgraph.

A) Globally installing Graph CLI

In the next step we will have to globally install The Graph CLI. The commands for npm or yarn (depending on which package manager you are using) are as follows:

Copy to Clipboard
Copy to Clipboard

B) Creating an example subgraph

Run the following command inside the folder on your machine you want to create a subgraph in:

Copy to Clipboard

Replace the placeholders with the following credentials:

  • <GITHUB_USERNAME> is required. It’s your GitHub username
  • <SUBGRAPH_NAME> is required. It’s the name of your subgraph project
  • <DIRECTORY> is optional. It’s the name of the directory that your subgraph is created in. Defaults to <SUBGRAPH_NAME>.

By running the command you create an example subgraph. You can use the subgraph to build your own subgraph on top of it. In the next tutorial, we will show you how to define a subgraph.

4. Deploying smart contract to Ganache.

After creating the sample subgraph via graph init you’re now ready compile and deploy a sample smart contract. By deploying the example smart contract, the subgraph you have created earlier will index it to Ganache. You need to run the following command to deploy the smart contract in the subgraph’s root directory (from step 3):

Copy to Clipboard

The command compiles the GravatarRegistry smart contract in order to deploy it to Ganache. A handful of transactions will be executed against the contract. This gives the subgraph the very first data to index.

Important: Don’t forget to copy the address (printed by truffle migrate) that the GravatarRegistry contract is deployed to.

5. Deploying to local Graph Node.

A) Adding the contract address

After you have copied the contract address, you can enter the root directory of your subgraph to deploy it to the local Graph Node. To do so, use this command:

Copy to Clipboard

B) Installing dependencies

Once the contract addresses deployed to the local Graph Node, you can install the dependencies of your subgraph. The second part of the command runs The Graph CLI code generation:

Copy to Clipboard

C) Allocating subgraph name

The next step is to allocate the subgraph name locally in the Graph Node:

Copy to Clipboard

D) Local deployment

The last step consists of deploying the subgraph to your local Graph Node. The logs that are being processed during the deployment can be found in the terminal output of the Graph Node.

Copy to Clipboard

6. Using the subgraph.

The final step of developing your subgraph in a local environment is to use it in a dApp build with React. To do so, open another terminal and select a sample dApp to clone. Make sure the decentralized application you clone is compatible with your subgraph.

Copy to Clipboard

Now you need to enter and configure the app directory so that it uses the GraphQL endpoint of the subgraph you created.

Copy to Clipboard

The last step is to install and start the dApp’s dependencies with this command:

Copy to Clipboard


You’ve learned now how to create an example subgraph and deploy it on a local testnet via Ganache. The next thing to learn is how to deploy it via the Hosted Service.

Go Back

Developer Knowledge Hub