Hello World (localhost + Docker)

2021-10-17 About 3 min

# Hello World (localhost + Docker)

Welcome to this SubQuery Hello World quick start. The quick start aims to show you how you get the default starter project running in Docker in a few simple steps.

# Learning objectives

At the end of this quick start, you should:

  • understand the required pre-requisites
  • understand the basic common commands
  • be able to navigate to localhost:3000 and view the playground
  • run a simple query to get the block height of the Polkadot mainnet

# Intended audience

This guide is geared towards new developers who have some development experience and are interested in learning more about SubQuery.

# Video guide

# Pre-requisites

You will need:

  • yarn or npm package manager
  • SubQuery CLI (@subql/cli)
  • Docker

You can run the following commands in a terminal to see if you already have any of these pre-requisites.

yarn -v (or npm -v)
subql -v
docker -v
1
2
3

For more advanced users, copy and paste the following:

echo -e "My yarn version is:" `yarn -v` "\nMy subql version is:" `subql -v`  "\nMy docker version is:" `docker -v`
1

This should return: (for npm users, replace yarn with npm)

My yarn version is: 1.22.10
My subql version is: @subql/cli/0.9.3 darwin-x64 node-v16.3.0
My docker version is: Docker version 20.10.5, build 55c4c88
1
2
3

If you get the above, then you are good to go. If not, follow these links to install them:

# 1. Initialise project

The first step when starting off with SubQuery is to run the subql init command. Let's initialise a start project with the name subqlHelloWorld. Note that only author is mandatory. Everything else is left empty below.

> subql init --starter subqlHelloWorld
Git repository:
RPC endpoint [wss://polkadot.api.onfinality.io/public-ws]:
Authors: sa
Description:
Version: [1.0.0]:
License: [Apache-2.0]:
Init the starter package... subqlHelloWorld is ready

1
2
3
4
5
6
7
8
9

Don't forget to change into this new directory.

cd subqlHelloWorld
1

# 2. Install dependencies

Now do a yarn or node install to install the various dependencies.

An example of yarn install

> yarn install
yarn install v1.22.10
info No lockfile found.
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
[4/4] 🔨  Building fresh packages...
success Saved lockfile.
✨  Done in 31.84s.
1
2
3
4
5
6
7
8
9

# 3. Generate code

Now run yarn codegen to generate Typescript from the GraphQL schema.

An example of yarn codegen

> yarn codegen
yarn run v1.22.10
$ ./node_modules/.bin/subql codegen
===============================
---------Subql Codegen---------
===============================
* Schema StarterEntity generated !
* Models index generated !
* Types index generated !
✨  Done in 1.02s.
1
2
3
4
5
6
7
8
9
10

Warning When changes are made to the schema file, please remember to re-run yarn codegen to regenerate your types directory.

# 4. Build code

The next step is to build the code with yarn build.

An example of yarn build

> yarn build
yarn run v1.22.10
$ tsc -b
✨  Done in 5.68s.
1
2
3
4

# 5. Run Docker

Using Docker allows you to run this example very quickly because all the required infrastructure can be provided within the Docker image. Run docker-compose pull && docker-compose up.

This will kick everything into life where eventually you will get blocks being fetched.

> #SNIPPET
subquery-node_1   | 2021-06-05T22:20:31.450Z <subql-node> INFO node started
subquery-node_1   | 2021-06-05T22:20:35.134Z <fetch> INFO fetch block [1, 100]
subqlhelloworld_graphql-engine_1 exited with code 0
subquery-node_1   | 2021-06-05T22:20:38.412Z <fetch> INFO fetch block [101, 200]
graphql-engine_1  | 2021-06-05T22:20:39.353Z <nestjs> INFO Starting Nest application...
graphql-engine_1  | 2021-06-05T22:20:39.382Z <nestjs> INFO AppModule dependencies initialized
graphql-engine_1  | 2021-06-05T22:20:39.382Z <nestjs> INFO ConfigureModule dependencies initialized
graphql-engine_1  | 2021-06-05T22:20:39.383Z <nestjs> INFO GraphqlModule dependencies initialized
graphql-engine_1  | 2021-06-05T22:20:39.809Z <nestjs> INFO Nest application successfully started
subquery-node_1   | 2021-06-05T22:20:41.122Z <fetch> INFO fetch block [201, 300]
graphql-engine_1  | 2021-06-05T22:20:43.244Z <express> INFO request completed

1
2
3
4
5
6
7
8
9
10
11
12
13

# 6. Browse playground

Navigate to http://localhost:3000/ and paste the query below into the left side of the screen and then hit the play button.

{
 query{
   starterEntities(last:10, orderBy:FIELD1_ASC ){
     nodes{
       field1
     }
   }
 }
}

1
2
3
4
5
6
7
8
9
10

SubQuery playground on localhost.

playground localhost

The block count in the playground should match the block count (technically the block height) in the terminal as well.

# Summary

In this quick start, we demonstrated the basic steps to get a starter project up and running within a Docker environment and then navigated to localhost:3000 and ran a query to return the block number of the mainnet Polkadot network.

Last update: October 17, 2021 08:07