Quick Start
Running TezGraph Using Docker-Compose
This guide serves to help a newcomer deploy a Tezos Indexer and TezGraph API in 4 commands or less. The only requirement for the user would be to have a machine with Docker and Docker-compose installed. The process involves downloading a docker-compose file and a dump of an already indexed database, bringing up the stack with docker-compose, and testing the TezGraph API.
Production TezGraph Links
It is not necessary to set up TezGraph locally. You can use our public TezGraph servers linked here.
Mainnet: https://mainnet.tezgraph.tez.ie/graphql
Edonet: https://edonet.tezgraph.tez.ie/graphql
Tezos RPC node
This guide makes use of a public Tezos node but for a fully private environment you use your own Tezos node. This can be done by changing the TEZOS_NODE
variable in the docker-compose.yml
file after it has been downloaded.
Prerequisites
- Docker
- Docker-compose
- About 15GB of available disk space for Edonet or 100GB for Mainnet
- Tezos RPC node
Steps to run TezGraph locally
Create a new directory and change directory
mkdir tezgraph-deploy && cd tezgraph-deployDownload the database dump and
docker-compose.yml
file. Thedocker-compose.yml
file will be different based on the Tezos network and whether you want the API to cater to queries to the database or not. Choose one of the following commands based on your use case.
Mainnet Queries and SubscriptionsMainnet Subscriptions onlycurl -LJo docker-compose.yml \ https://gitlab.com/tezgraph/tezgraph/-/raw/master/examples/mainnet-docker-compose.yml \ && curl -LJo mainnet-docker-compose-dump.sql.gz https://storage.googleapis.com/tezgraph-db-snaps/$(curl https://storage.googleapis.com/tezgraph-db-snaps/mainnet.json| jq -r '.latest')
Startup the Indexer, Database, and API using docker compose. Follow the logs in the console to see how the stack is progressing. There are a few pitfalls to watch out for listed in the Pitfalls and Known Issues section below. An example of this would be that the database takes some time to start up, and there will be some errors in the console that can be ignored.
docker-compose upA good indication of the stack being ready and waiting for tests is when you see something similar to the following in the console:
indexer_database | LOG: starting PostgreSQL 13.1 (Debian 13.1-1.pgdg100+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 8.3.0-6) 8.3.0, 64-bitindexer_database | LOG: listening on IPv4 address "0.0.0.0", port 5432indexer_database | LOG: listening on IPv6 address "::", port 5432indexer_database | LOG: listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"indexer_database | LOG: database system was shut down at 2020-12-15 05:54:49 UTCindexer_database | LOG: database system is ready to accept connection
Testing
Once the stack is up and running you can navigate to https://localhost:3000/graphql. The page will look like this:
You can then execute GraphQL queries on the database through the TezGraph API. An example of a test on Mainnet would be:
query {account (address: "tz1MBidfvWhJ64MuJapKExcP5SV4HQWyiJwS"){transactions {edges {node {source,kind}}}}}
Pitfalls and Known Issues
- If there are any issues that are not listed here or that you are unable to overcome, you can restart the process by bringing down the stack and deleting the volumes using the following command:
docker-compose down -v
The most important thing to note is that the database will take time to restore from the backup. The database restore time can differ based on the Tezos network, CPU, or RAM on the host, but the approximate times are 10 minutes for Edonet and 70 minutes for Mainnet. During this time, you will not be able to execute queries on the database. When you try and execute a query, you will receive a response similar to:
{"errors": [{"message": "\nInvalid `prisma.queryRaw()` invocation:\n\n\n Can't reach database server at `indexer_database`:`5432`\n\nPlease make sure your database server is running at `indexer_database`:`5432`.","locations": [{"line": 2,"column": 3}],"path": ["account"],"extensions": {"code": "INTERNAL_SERVER_ERROR","exception": {"clientVersion": "2.12.1","stacktrace": ["Error: ","Invalid `prisma.queryRaw()` invocation:","",""," Can't reach database server at `indexer_database`:`5432`","","Please make sure your database server is running at `indexer_database`:`5432`."," at PrismaClientFetcher.request (/app/node_modules/@prisma/client/runtime/index.js:79361:15)"," at processTicksAndRejections (internal/process/task_queues.js:97:5)"]}}}],"data": null}Another known issue is sometimes after the stack has started, the TezGraph container is still unable to connect to the database container (You will see an error similar to the one above), the easiest way to remedy this issue is to bring the stack down by typing
ctrl + c
, waiting for the containers to stop gracefully, and then bringing the stack up again using thedocker-compose up
command.Here are some of the errors in the console that can safely be ignored while the stack is starting up and the database is being restored.
indexer_database | ERROR: canceling autovacuum taskindexer_database | CONTEXT: while scanning block 190427 of relation "public.balance"indexer_database | automatic vacuum of table "indexer.public.balance"
indexer_database | LOG: checkpoints are occurring too frequently (22 seconds apart)indexer_database | HINT: Consider increasing the configuration parameter "max_wal_size".
indexer | Database connection error: Failed to connect to <postgresql://indexer:_@indexer_database:5432/indexer?sslmode=disable>: Connection failure: could not connect to server: Connection refusedindexer | Is the server running on host "indexer_database" (XXX.XXX.XXX.XXX) and acceptingindexer | TCP/IP connections on port 5432?indexer |indexer | To get more information about specifying how to connect to the database, run:indexer | /indexer/tezos-indexer --helpindexer exited with code 3
This error will repeatedly happen until the database becomes available and should be ignored until then.