Skip to content
ENSNode

Building and Using ENSRainbow Docker Images

ENSRainbow can be run as a Docker image, which includes the application server and scripts to manage its data. Official images are hosted on GitHub Container Registry (GHCR) at ghcr.io/namehash/ensnode/. You can view all available image tags and versions on the GitHub package page.

Key Data Handling Strategy:

The ENSRainbow Docker image is designed to be lightweight. The LevelDB database required for its operation is not baked into the image during the build process. Instead, the requested database is downloaded and managed at runtime by an entrypoint.sh script within the container. This process is triggered when you run the container with both of the following requirements:

  1. A Docker volume mounted to /app/apps/ensrainbow/data (the internal data path).
  2. Specific environment variables set: DB_SCHEMA_VERSION, LABEL_SET_ID, and LABEL_SET_VERSION.

This approach allows for flexible data updates and management without needing to rebuild the application image.

The pre-built image from GHCR is the recommended way to run ENSRainbow.

Building the Application Image (Optional)

Section titled “Building the Application Image (Optional)”

If you need to build the ENSRainbow application image from source (e.g., for development or testing custom changes), you can use the Dockerfile located in the apps/ensrainbow/ directory.

Terminal window
# from the monorepo root
docker build -f apps/ensrainbow/Dockerfile -t ghcr.io/namehash/ensnode/ensrainbow:latest .

This command builds an image containing the ENSRainbow application and the entrypoint.sh script responsible for runtime data provisioning. The resulting image will behave the same way as the official pre-built image regarding data handling.

(Note: The apps/ensrainbow/Dockerfile uses a multi-stage setup for build optimizations. Data handling is deferred to the entrypoint.sh script at runtime.)

Available Pre-built Image on GHCR

Section titled “Available Pre-built Image on GHCR”

The following official image is available on GHCR and is recommended for use:

  • ghcr.io/namehash/ensnode/ensrainbow:latest: The standard ENSRainbow application image.

You can pull this image using:

Terminal window
docker pull ghcr.io/namehash/ensnode/ensrainbow:latest

Runtime Data Provisioning via entrypoint.sh

Section titled “Runtime Data Provisioning via entrypoint.sh”

The ENSRainbow application image (whether self-built or pulled from GHCR) uses the entrypoint.sh script to manage the LevelDB data at runtime.

When the container starts:

  • The script checks the designated data directory (mounted via a volume, typically at /app/apps/ensrainbow/data).
  • If the correct data (matching DB_SCHEMA_VERSION, LABEL_SET_ID, LABEL_SET_VERSION environment variables) is present and valid, the server starts.
  • If data is missing, outdated, or invalid, the script will attempt to download the appropriate pre-built database archive.
  • A marker file (.ensrainbow_db_ready) is used within the data directory to indicate a successfully prepared database.

This ensures that the container always runs with the correct and validated dataset. For detailed instructions on running the image with persistent storage and managing these environment variables, please refer to the Persistent Storage with Docker section in the main contribution guide.