Quickstart with Docker Compose and AWS

Sometimes it is nice to not rely on long docker commands. Running with Docker compose is very similar to using raw Docker and you can find a full specification of the format in the Docker docs.

1. Setup validator key

Follow the guide here for creating agent keys with AWS KMS.

2. Create S3 bucket for signatures

Follow the guide here for creating and configuring an S3 bucket for your validator to write signatures to.

3. (AVS Operators Only) Register with Hyperlane AVS

If you are an AVS operator, follow the guide here to register with the Hyperlane AVS.

4. Setup validator environment

Create config files

In this example, we will run three chains.

mkdir -p ethereum/hyperlane_db optimism/hyperlane_db base/hyperlane_db && \
touch ethereum/config.json optimism/config.json base/config.json docker-compose.yml .env.ethereum .env.optimism .env.base

Edit each config.json

You can read more about Agent Configs here.

Parameter	Description
customRpcUrls	A comma-separated list of performant RPC endpoints for the chain you wish to support. We recommend using paid providers to avoid rate limiting.
chains.ethereum	Should be changed to chains.base in the base/config.json, and chains.optimism in optimism/config.json.
signer.region	Should be adjusted to your AWS region.
validator.region	Should be adjusted to your AWS region.
signer.id	Should be adjusted to your AWS KMS id you configured in step 3, prefixed with alias/.
validator.id	Should be adjusted to your AWS KMS id you configured in step 3, prefixed with alias/.
originChainName	Should be the chain you are validating.
checkpointSyncer.bucket	Should reflect the name of the S3 bucket.
checkpointSyncer.folder	The name of the folder the validator will use within the bucket. You may use the same bucket for multiple validators, but ensure each folder name is unique per validator.
reorgPeriod	May be different for each chain. Find the reorgPeriods.

Here is an example agent config.

{
  "chains": {
    "ethereum": {
      "customRpcUrls": "https://eth.llamarpc.com,https://rpc.mevblocker.io",
      "signer": {
        "region": "us-east-1",
        "type": "aws",
        "id": "alias/hyperlane-validator-signer"
      }
    }
  },
  "originChainName": "ethereum",
  "db": "/mnt/hyperlane_db",
  "validator": {
    "id": "alias/hyperlane-validator",
    "type": "aws",
    "region": "us-east-1"
  },
  "checkpointSyncer": {
    "bucket": "hyperlane-validator-signatures",
    "region": "us-east-1",
    "type": "s3",
    "folder": "ethereum"
  },
  "reorgPeriod": 14,
  "metricsPort": "9090"
}

Edit each .env file

You should change the service name, db path, and config file locations to match the folders created for each chain.

AWS_ACCESS_KEY_ID=<Your AWS access key ID>
AWS_SECRET_ACCESS_KEY=<Your AWS secret access key>
DB_PATH=./ethereum/hyperlane_db
METRICS_PORT=9090 # Default is 9090, should match port set in config.json
CONFIG_FILE=./ethereum/config.json
SERVICE_NAME=ethereum

5. Configure Docker Compose (docker-compose.yml)

version: '3.8'

services:
  validator:
    image: gcr.io/abacus-labs-dev/hyperlane-agent:7a8478b-20240703-113821
    command: ./validator
    container_name: ${SERVICE_NAME}-validator
    ports:
      - "${METRICS_PORT}:9090/tcp"
    environment:
      CONFIG_FILES: /config.json
      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
    configs:
      - source: config_${SERVICE_NAME}
        target: /config.json
    volumes:
      - ${DB_PATH}:/mnt/hyperlane_db
    restart: unless-stopped
    env_file:
      - .env

configs:
  config_ethereum:
    file: ./ethereum/config.json
  config_optimism:
    file: ./optimism/config.json
  config_base:
    file: ./base/config.json

Your directory structure should look similar to this:

.
├── base
│   ├── config.json
│   └── hyperlane_db
├── docker-compose.yml
├── ethereum
│   ├── config.json
│   └── hyperlane_db
├── .env.base
├── .env.ethereum
├── .env.optimism
└── optimism
    ├── config.json
    └── hyperlane_db

6. Run the Hyperlane validators

Bring the containers up:

Remember to fund your validator address so the validator can announce.

docker-compose --env-file .env.ethereum up -d
docker-compose --env-file .env.optimism up -d
docker-compose --env-file .env.base up -d

Ensure there are no errors:

docker logs -f ethereum-validator