For AI agents: the documentation index is at /llms.txt. Markdown versions of pages are available by appending .md to the URL.
Skip to main content

Self-Hosting Your Blockchain Indexer

info

This documentation page is actively being improved. Check back regularly for updates and additional information.

While Envio offers a fully managed cloud hosting solution via Envio Cloud, you may prefer to run your blockchain indexer on your own infrastructure. This guide covers everything you need to know about self-hosting Envio indexers.

note

We deeply appreciate users who choose Envio Cloud, as it directly supports our team and helps us continue developing and improving Envio's technology. If your use case allows for it, please consider the hosted option.

Why Self-Host?​

Self-hosting gives you:

  • Complete Control: Manage your own infrastructure and configurations
  • Data Sovereignty: Keep all indexed data within your own systems
Disclaimer

Self Hosting can be done with a variety of different infrastructure, tools and methods. The outline below is merely a starting point and does not offer a full production level solution. In some cases advanced knowledge of infrastructure, database management and networking may be required for a full production level solution.

Prerequisites​

Before self-hosting, ensure you have:

  • Docker installed on your host machine, or Node.js 22.15.0 or newer to run the indexer directly
  • A PostgreSQL database the indexer can reach
  • Sufficient storage for blockchain data and the indexer database
  • Adequate CPU and memory resources (requirements vary based on chains and indexing complexity)
  • Required HyperSync and/or RPC endpoints
  • Envio API token for HyperSync access (ENVIO_API_TOKEN) - required for continued access. See API Tokens.

Getting Started​

In general, if you want to self-host, you will likely use a Docker setup. For a working example, check out the local-docker-example repository. It contains a minimal Dockerfile and docker-compose.yaml that configure the Envio indexer together with PostgreSQL and Hasura.

Configuration Explained​

The compose file in that repository sets up three main services:

  1. PostgreSQL Database (envio-postgres): Stores your indexed data
  2. Hasura GraphQL Engine (graphql-engine): Provides the GraphQL API for querying your data
  3. Envio Indexer (envio-indexer): The core indexing service that processes blockchain data

Environment Variables​

The configuration uses environment variables with sensible defaults. For production, you should customize:

  • Envio API token (ENVIO_API_TOKEN)
  • Database connection (ENVIO_PG_HOST, ENVIO_PG_PORT, ENVIO_PG_USER, ENVIO_PG_PASSWORD, ENVIO_PG_DATABASE, and ENVIO_PG_SSL_MODE for a managed database)
  • Hasura connection (HASURA_GRAPHQL_ENDPOINT, for example http://graphql-engine:8080/v1/metadata, and HASURA_GRAPHQL_ADMIN_SECRET), or ENVIO_HASURA=false to run without Hasura. With NODE_ENV=production, set the HASURA_GRAPHQL_* variables even when Hasura is off (see Production mode)
  • Resource limits based on your workload requirements

If you set NODE_ENV=production, the Postgres connection and Hasura variables lose their dev defaults, and the indexer won't start until they are set. ENVIO_PG_PASSWORD (testing) and ENVIO_PG_SCHEMA (public) keep their defaults, so set the password yourself. See Production mode for the full list.

Running the Indexer​

The indexer container runs envio start (the start script in package.json). It:

  1. Runs codegen, so the image only needs your project files and dependencies.
  2. On the first run, creates the tables in ENVIO_PG_SCHEMA (default public) and, when Hasura is enabled, tracks them in Hasura.
  3. On later runs, resumes from the last checkpoint.
  4. Serves /metrics and /healthz on ENVIO_INDEXER_PORT (default 9898). Point your container health check at /healthz on that port. See Observability.

envio start -r deletes the indexed data and starts over. A restart after changing the config, the schema or the envio version stops with The following config changes are incompatible with the existing indexer data:. Re-index with -r, or run the new version against a fresh ENVIO_PG_SCHEMA and switch over once it has synced. See Common Issues.

To match the versions envio dev uses locally, run postgres:18.3 and hasura/graphql-engine:v2.43.0.

Getting Help​

If you encounter issues with self-hosting:

tip

For most production use cases, we recommend using Envio Cloud to benefit from automatic scaling, monitoring, and maintenance.