Skip to main content

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.

customRpcUrlsA comma-separated list of performant RPC endpoints for the chain you wish to support. We recommend using paid providers to avoid rate limiting.
chains.ethereumShould be changed to chains.base in the base/config.json, and chains.optimism in optimism/config.json.
signer.regionShould be adjusted to your AWS region.
validator.regionShould be adjusted to your AWS region.
signer.idShould be adjusted to your AWS KMS id you configured in step 3, prefixed with alias/.
validator.idShould be adjusted to your AWS KMS id you configured in step 3, prefixed with alias/.
originChainNameShould be the chain you are validating.
checkpointSyncer.bucketShould reflect the name of the S3 bucket.
checkpointSyncer.folderThe 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.
reorgPeriodMay be different for each chain. Find the reorgPeriods.

Here is an example agent config.

"chains": {
"ethereum": {
"customRpcUrls": ",",
"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>
METRICS_PORT=9090 # Default is 9090, should match port set in config.json

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

version: '3.8'

command: ./validator
container_name: ${SERVICE_NAME}-validator
- "${METRICS_PORT}:9090/tcp"
CONFIG_FILES: /config.json
- source: config_${SERVICE_NAME}
target: /config.json
- ${DB_PATH}:/mnt/hyperlane_db
restart: unless-stopped
- .env

file: ./ethereum/config.json
file: ./optimism/config.json
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