Deploying ENSRainbow with Docker

NameHash Labs publishes the latest version of ENSRainbow as a docker container. The Docker image is lightweight and downloads the requested database at runtime based on environment variables.

Quick Start

For a quick test setup with test data:

# Create a directory for persistent data storage
mkdir -p ~/my_ensrainbow_data

# Run with the ens-test-env data
docker run -d --name ensrainbow \
  -v ~/my_ensrainbow_data:/app/apps/ensrainbow/data \
  -e DB_SCHEMA_VERSION="3" \
  -e LABEL_SET_ID="ens-test-env" \
  -e LABEL_SET_VERSION="0" \
  -p 3223:3223 \
  ghcr.io/namehash/ensnode/ensrainbow:latest

The service will be available at http://localhost:3223.

Storage Requirements

The ENSRainbow storage needed for a set of rainbow tables for healing unknown labels ranges from 1 MB to dozens of GB depending on the label set ID and label set version. See System Requirements for details.

Production Setup

For full ENS Subgraph backward compatibility use the subgraph label set ID and 0 as the label set version (for maximized label healing use the searchlight label set ID and the latest label set version):

# Create a directory for persistent data storage
mkdir -p ~/ensrainbow_production_data

# Run with production data
docker run -d --name ensrainbow_production \
  -v ~/ensrainbow_production_data:/app/apps/ensrainbow/data \
  -e DB_SCHEMA_VERSION="3" \
  -e LABEL_SET_ID="subgraph" \
  -e LABEL_SET_VERSION="0" \
  -p 3223:3223 \
  ghcr.io/namehash/ensnode/ensrainbow:latest

Required Environment Variables

Complete Environment Variable Reference

See the Configuration page for detailed descriptions of all environment variables and configuration options.

The Docker deployment requires these three variables for data management:

Variable	Purpose	Example
DB_SCHEMA_VERSION	Identifies the expected on-disk database schema version	3
LABEL_SET_ID	Chooses which label-set to download	subgraph, ens-test-env
LABEL_SET_VERSION	Downloads prebuilt snapshot containing all data from version 0 through this version	0

Persistent Storage

Persistent Storage Required

You must mount a Docker volume to /app/apps/ensrainbow/data to ensure the database persists between container restarts. Without persistent storage, the database will be re-downloaded every time the container starts.

Using Named Docker Volumes (Recommended)

# Create a named volume (only needs to be done once)
docker volume create ensrainbow_db_volume

# Run with named volume
docker run -d --name ensrainbow \
  -v ensrainbow_db_volume:/app/apps/ensrainbow/data \
  -e DB_SCHEMA_VERSION="3" \
  -e LABEL_SET_ID="subgraph" \
  -e LABEL_SET_VERSION="0" \
  -p 3223:3223 \
  ghcr.io/namehash/ensnode/ensrainbow:latest

Using Host Directories

# Create a directory on your host machine
mkdir -p ~/ensrainbow_data

# Run with host directory mount
docker run -d --name ensrainbow \
  -v ~/ensrainbow_data:/app/apps/ensrainbow/data \
  -e DB_SCHEMA_VERSION="3" \
  -e LABEL_SET_ID="subgraph" \
  -e LABEL_SET_VERSION="0" \
  -p 3223:3223 \
  ghcr.io/namehash/ensnode/ensrainbow:latest

Docker Compose

To use ENSRainbow as part of a Docker Compose setup, use the following service definition:

version: '3.8'

services:
  ensrainbow:
    container_name: ensrainbow
    image: ghcr.io/namehash/ensnode/ensrainbow:latest
    environment:
      - DB_SCHEMA_VERSION=3
      - LABEL_SET_ID=subgraph
      - LABEL_SET_VERSION=0
    volumes:
      - ensrainbow_data:/app/apps/ensrainbow/data
    ports:
      - "3223:3223"
    restart: unless-stopped

volumes:
  ensrainbow_data:

For the ens-test-env:

version: '3.8'

services:
  ensrainbow:
    container_name: ensrainbow_test
    image: ghcr.io/namehash/ensnode/ensrainbow:latest
    environment:
      - DB_SCHEMA_VERSION=3
      - LABEL_SET_ID=ens-test-env
      - LABEL_SET_VERSION=0
    volumes:
      - ensrainbow_test_data:/app/apps/ensrainbow/data
    ports:
      - "3223:3223"
    restart: unless-stopped

volumes:
  ensrainbow_test_data:

How Data Download Works

1. First Run: When the container starts with an empty volume, it downloads the specified pre-built ENSRainbow database archive based on the environment variables
2. Subsequent Runs: The container detects existing data and skips the download, using the persisted database
3. Data Validation: The container validates the existing data on startup

Understanding Label Set Versions

When you specify LABEL_SET_VERSION=N, the system:

• Downloads a single file: {LABEL_SET_ID}_{LABEL_SET_VERSION}.tgz (e.g., subgraph_2.tgz)
• Contains cumulative data: This file includes all label-to-labelhash mappings from version 0 through version N
• Provides deterministic results: The server will only use data up through version N, ensuring consistent healing results even if newer versions become available

Version Behavior

Setting LABEL_SET_VERSION=2 does not download separate files for versions 0, 1, and 2. Instead, it downloads one prebuilt database snapshot that contains the cumulative data from all those versions.

Port Mapping

The port mapping (-p 3223:3223 or ports in docker-compose) is only needed if you want to access ENSRainbow from the host machine. If you’re only accessing it from other containers in the same network, you can omit the port mapping.

Next Steps

Configuration Reference Complete environment variable documentation and configuration options

Troubleshooting Common Docker deployment issues and solutions