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

1. Running Postgres

Ensure Postgres in the background, providing its connection details to ENSIndexer via DATABASE_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 build 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 built images with:

docker compose up -d

• ENSIndexer: Available at http://localhost:42069
• ENSApi: 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.