# 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:

```bash
# 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`.

:::note[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](/docs/services/ensrainbow/contributing/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):

```bash
# 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

:::tip[Complete Environment Variable Reference]
See the [Configuration](/docs/services/ensrainbow/usage/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

:::important[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)

```bash
# 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

```bash
# 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](https://docs.docker.com/compose/) setup, use the following service definition:

```yml
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:

```yml
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

:::caution[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.
:::

:::note[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](/docs/services/ensrainbow/usage/configuration/)

[Troubleshooting](/docs/services/ensrainbow/usage/troubleshooting/)