Ecosystem Roles
Running a Relayer
Running with Docker

Deploying using Docker

A Webb relayer can be spun up quickly using Docker. For more information on installing Docker, please visit the official Docker docs (opens in a new tab).

By the end of this document, you will have set up a Webb Relayer at a publicly accessible via an endpoint behind a reverse proxy, and fulfill the requirements for listing your relayer on

Getting Started

These instructions assume the user has access to a server on any Linux VM, and is logged into a user with sudo permissions.

Before we begin we want to ssh into the VM and update the system using the specified system package manager:

apt update
# Update packages
sudo apt update && sudo apt upgrade


It is a requirement to have Docker installed on the Linux machine, for instructions on how to install Docker on the machine please visit the offical Docker installation documentation here (opens in a new tab).

Configuring Relayer for Docker

Before building and running a Webb relayer, we need create a set of configuration files for the relayer to be aware of the smart contracts and the features we intend to make use of. They're are three distinct configurations to consider, for an overview of each them please refer to the Relayer Overview page here.

Let's create a new directory called webb-relayer. This is where we will store all our configuration files, and secrets.

mkdir -p ~/webb-relayer/{config,data,secrets}

Data Query Configuration

This section will outline the minimum requirements to setup a Webb relayer for data querying purposes. For an extensive review of all data querying configuration and available endpoints please refer to the data-querying page here, the private transaction relaying page here, or the signature relaying page here.

We want to create a toml file to outline our configuration details:

# main.toml
nano ~/webb-relayer/config/main.toml

Let's update to include the required fields for data querying:

# Webb Relayer Network Port
# default: 9955
port = 9955
governance-relay = false
data-query = true
private-tx-relay = false

For this example, we will use ETH Goerli Testnet (chain_id = 5). Create a file for the configuration related to this chain:

# goerli.toml
nano ~/webb-relayer/config/goerli.toml

Next we want to add the required fields to query the data from the Anchor deployed on Goerli Testnet. For an exhasutive list of configuration please refer to the Configuration Options doc. Let's add the following to the file:

# Block which represents properties for a network
name = "goerli"
# Http(s) Endpoint for quick Req/Res
http-endpoint = "$GOERLI_HTTPS_URL"
# Websocket Endpoint for long living connections
ws-endpoint = "$GOERLI_WSS_URL"
# Block Explorer
# Optinal, and used for generating clickable links
# for transactions that happen on this chain.
explorer = ""
# chain specific id from evm opcode
chain-id = 5
# Value to indicate that the relayer should enable services for this chain
enabled = true
# No block confirmations required to process it.
block-confirmations = 2
# Block which represents the configuration for a supported contract on the network
# The contract can be one of these values
# - VAnchor (Variable Anchor)
# - SignatureBridge
contract = "VAnchor"
# The address of the contract
address = "0x98c1024dfd61a8f7439108acedcb51a27754f2af"
# The deployed block number of the contract. When a relayer does not have information for
# this contract in its store, it will start to sync and query for relevant historical data
# starting at this block number
deployed-at = 7865473
# Configuration for the events watcher of this contract. The events-watcher can be switched on/off
# and the polling interval specifies the period of time (in ms) that the events-watcher thread
# will wait before issuing another query for new events.
events-watcher = { enabled = true, polling-interval = 15000 }

Setting up .env File

As you may have noticed, there are a few environment variables inside the configuration file, and we will have to supply them. To do so, lets create a .env file with these values:

nano ~/webb-relayer/.env

Add the following fields:

# The internal Webb Relayer Port
# this will not be the public port, but will be used internally
# inside docker.
# Change this version to the latest Docker image by the relayer
# from here:
# These are related to the Reverse Proxy we will use.
# Your email address. Mainly used when creating an ACME
# account with your CA, and is highly recommended
# in case there are problems with your certificates.
LETSENCRYPT_EMAIL=[email protected]
# This will be your domain for the relayer
# Make sure it points to the public IP for your VM.
# Here you can provide or use your RPC endpoints,
# But for this example, we will use a free-to-use public RPC endpoints
# From

Great we have successfully setup our data-querying configuration. Now we need to setup the Docker container that will run the reverse proxy and the Webb relayer.

Creating Docker Compose File

The section will cover setting up the required docker service in a docker compose file. Let's start by creating a docker-compose file:

nano ~/webb-relayer/docker-compose.yml

Add the following lines:

version: "3"
    image: caddy:alpine
    container_name: caddy
    restart: unless-stopped
    env_file: .env
      - "80:80"
      - "443:443"
      - $PWD/config/Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    container_name: webb_relayer
    env_file: .env
      - caddy
      - $PWD/config:/config
      - relayer_data:/store
    restart: always
    command: /webb-relayer -vvv -c /config
    driver: local
      type: none
      o: bind
      device: $PWD/data
    driver: local
      type: none
      o: bind
      device: $PWD/secrets

Caddy Reverse Proxy

This guide makes use of Caddy (opens in a new tab) as a reverse proxy. Caddy is a powerful reverse proxy that makes it incredibly easy to setup with only a few lines. Let's take a look at the configuration:

nano ~/webb-relayer/config/Caddyfile

Add the following lines:

	# Remove the below line to disable debug logging, could be helpful
  # but noisy.
	# Here we are using the staging server to test our setup
	# but you can remove this line to use the production server
	# when you are ready to go live
	# If you are testing this locally, in your machine, or if you are
	# not using a domain name yet, you can turn off the Auto HTTPS feature
	# by uncommenting the line below
	# auto_https off
relayer.{$DOMAIN} {
	reverse_proxy {
		to http://webb_relayer:{$WEBB_PORT}

We have now successfully setup the reverse proxy, and we are ready to run the relayer.

Running the Relayer

Go to ~/webb-relayer and then fire-up the following command:

compose up
cd ~/webb-relayer
# Then run docker
docker compose up # add -d if you want to run it in the backgroud.

You should see a lot of logs, and if everything is working correctly, we should be able to query our relayers endpoint to view the configuration we outlined above.

Test the Setup

Let's make sure we have successfully setup a data-querying relayer. To do so, we will query the relayer's endpoint:

# Replace this with your domain name, that you added inside the .env file
# if running locally, you should just go assume the DOMAIN is localhost:9955

If everything is working correctly, you should see a response similar to this:

  evm: {
    "5": {
      name: "goerli",
      enabled: true,
      chainId: 5,
      beneficiary: null,
      contracts: [
          contract: "VAnchor",
          address: "0x98c1024dfd61a8f7439108acedcb51a27754f2af",
          deployedAt: 7865473,
          eventsWatcher: {
            "enable-data-query": true,
            enabled: true,
            pollingInterval: 15000,
          withdrawConfig: null,
          proposalSigningBackend: null,
          linkedAnchors: null,
  substrate: {},
  cosmwasm: {},
  experimental: {
    "smart-anchor-updates": false,
    "smart-anchor-updates-retries": 0,
  features: {
    "data-query": true,
    "governance-relay": false,
    "private-tx-relay": false,

To configure your relayer further, checkout our Config directory (opens in a new tab) in our GitHub.

Dapp Integration

After completing the above steps, submit a PR with changes for your https endpoint in the Webb Dapp (opens in a new tab) repo.