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/docker-compose.yml in the docker directory for a full spec on the relationship between services.

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

1. Running ENSDb

Ensure ENSDb is running in the background, providing its connection details to ENSIndexer via ENSDB_URL.

2. Running ENSRainbow

# from monorepo root
pnpm run -F @ensnode/ensrainbow serve

# or from apps/ensrainbow
pnpm run serve

3. Running ENSIndexer

Note

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

Running ENSIndexer in Development

Follow instructions in the ENSIndexer Contribution Guide to set up your local environment.

# from monorepo root
pnpm run -F ensindexer dev

# or from apps/ensindexer
pnpm run dev

4. Running ENSApi

Note

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

# from monorepo root
pnpm run -F ensapi dev

# or from apps/ensapi
pnpm run dev

5. Running ENSAdmin

Note

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

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

# from monorepo root
pnpm run -F ensadmin dev

# or from apps/ensadmin
pnpm run dev

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

Building the Docker Images

Before running docker compose the images must be built with the latest changes: see the Building Docker Images guide.

If you make changes in the application code and wish to run those updates, you must build the relevant Docker container again.

Running the Applications

Run the base stack with:

docker compose -f docker/docker-compose.yml up -d

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

For more compose files (devnet, CI), configuration options, and all available commands, see the Deploying with Docker guide and docker/README.md.

Stopping the Applications

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

docker compose -f docker/docker-compose.yml down

Postgres Volume

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