Deploying ENSNode with Docker

The Docker images are the easiest way to run or deploy the ENSNode suite of services, both locally and in the cloud.

All commands below are run from the monorepo root.

Postgres Requirement

ENSIndexer runs CREATE EXTENSION IF NOT EXISTS pg_trgm at startup to back partial-name search indexes. If you’re swapping out the bundled postgres:17 image for a managed or custom Postgres, make sure the pg_trgm extension is available for installation (it ships with stock Postgres contrib and is available for installation on most managed providers).

ENSNode provides several Docker Compose files for different use cases:

• docker/docker-compose.yml — base stack for mainnet/sepolia: ensindexer, ensapi, ensrainbow, ensadmin, ensdb (postgres)
• docker/docker-compose.devnet.yml — full stack against local devnet (ens-test-env), works out of the box with no configuration required

To inspect the fully resolved config for any compose file (resolves all extends):

docker compose -f docker/docker-compose.yml config

Choosing ENSNODE_TAG

ENSNODE_TAG controls which ENSNode image version is pulled for ensindexer, ensapi, ensrainbow, and ensadmin.

• If ENSNODE_TAG is not set, compose files use the default tag baked into service definitions.
• For reproducible environments, pin a specific release tag.
• For quick local testing, you can override it temporarily from the shell.

• One-off override for a single command.

  ENSNODE_TAG=1.10.1 docker compose -f docker/docker-compose.yml up -d

• Persistent override using docker/.env. Docker Compose picks it up automatically.

  echo "ENSNODE_TAG=1.10.1" >> docker/.env
  docker compose -f docker/docker-compose.yml up -d

• Persistent override using docker/envs/.env.docker.local. Pass it explicitly with --env-file.

  echo "ENSNODE_TAG=1.10.1" >> docker/envs/.env.docker.local
  docker compose --env-file docker/envs/.env.docker.local -f docker/docker-compose.yml up -d

• Persistent override using export.

  export ENSNODE_TAG=1.10.1
  docker compose -f docker/docker-compose.yml up -d

Mainnet / Sepolia

Copy the example env file and configure it (one-time setup):

cp docker/envs/.env.docker.example docker/envs/.env.docker.local

Configure Environment Variables

Edit docker/envs/.env.docker.local to set NAMESPACE, PLUGINS, and your RPC endpoints (for example ALCHEMY_API_KEY or RPC_URL_1), then run:

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

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

# Stop and remove volumes
docker compose -f docker/docker-compose.yml down -v

Local devnet

This stack is primarily intended for engineers developing ENS infrastructure and testing against a local chain.

Configuration is optional. To customize defaults (e.g. change PLUGINS), copy the example as in previous step and edit it.

Otherwise, skip setup and run directly:

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

To start only specific services:

# Devnet + core services (no ENSAdmin)
# Useful when you do not need UI
docker compose -f docker/docker-compose.devnet.yml up -d ensindexer ensapi

# Devnet only
# Useful when you want only a local EVM chain
docker compose -f docker/docker-compose.devnet.yml up devnet

# Or
pnpm devnet

To stop stacks:

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

View Docker Compose files on GitHub Browse the full docker/ directory including service definitions.

Port Mappings

Note that while the default docker/docker-compose.yml exposes each container’s port to the host machine (useful for development), you may only wish to expose ENSApi’s 4334 and avoid exposing services like ENSRainbow, ENSAdmin, and Postgres to the wider internet.