ENSNode Development and Contributions

Note

This guide covers running ENSNode locally for development and contributions.

Prerequisites

• Git
• Postgres 17
• Node.js
  • It’s recommended you install Node.js through nvm or asdf.
  • see .nvmrc and .tool-versions for the specific version of Node.js
• pnpm
  • Run npm install -g pnpm or see other installation options.

Prepare Workspace

Clone this repository:

git clone git@github.com:namehash/ensnode.git
cd ensnode

Install Dependencies

pnpm install

Running ENSNode

Note

ENSNode is a suite of services, and some depend on others. Refer to the docker-compose.yml at the root of the monorepo for a full spec on the relationship between services.

View docker-compose.yml on GitHub See the Docker Compose configuration file defining service relationships

Configuring Environment Variables

cd apps/ensindexer
cp .env.local.example .env.local

Environment Variable Configuration Options

Note

ENSIndexer’s .env.local should be placed at apps/ensindexer/.env.local, not at the monorepo root.

1. Running Postgres

Ensure Postgres in the background, providing its connection details to ENSIndexer via DATABASE_URL.

2. Running ENSRainbow

Running ENSRainbow in Development

To run ENSRainbow in development, the rainbow table data dir must be available. Follow instructions in the ENSRainbow Contribution Guide to set up your local environment.

pnpm run serve

3. Running ENSIndexer

# from monorepo root
pnpm run -F ensindexer dev

# or from apps/ensindexer
pnpm run dev

View Ponder Documentation Learn more about running Ponder indexers in development and production

4. Running ENSAdmin

cd apps/ensadmin
cp .env.local.example .env.local

# from monorepo root
pnpm run -F ensadmin dev

# or from apps/ensadmin
pnpm run dev

Note

ENSAdmins’s .env.local should be placed at apps/ensadmin/.env.local, not at the monorepo root.

Using Docker Compose

You can use Docker Compose to set up the ENSNode suite, along with its dependencies.

Docker in Development

Re-building Docker containers is slow and inefficient, and doesn’t lend itself to rapid development. The first half of this guide showed how to run ENSNode on your host machine, for faster iteration and maximum control. The Docker Compose spec is helpful for describing the suite of services and running them in a structured way, which we’ll discuss below.

Prerequisites

Before you can use Docker Compose, ensure you have the following installed on your machine:

• Docker
• Docker Compose

Running the Applications

To start the ENSNode services using Docker Compose, follow these steps:

docker compose up

• ENSIndexer: Available at http://localhost:42069
• ENSRainbow: Available at http://localhost:3223
• ENSAdmin: Available at http://localhost:4173
• PostgreSQL: Available on port 5432

Stopping the Applications

To stop the running applications, you can press Ctrl + C in the terminal where Docker Compose is running. If you want to remove the containers and networks created by Docker Compose, you can run:

docker compose down

Postgres Volume in this docker-compose.yml

docker compoe down will not delete the Postgres data volume defined here, as it is a named volume. To fully delete the Postgres data volume and start from scratch, use docker compose down -v.

Building Docker Images

For detailed instructions on building Docker images for ENSNode components, see the Building Docker Images guide.