Skip to content

Run A Node

This guide shows you how to run a validator node or an RPC node.

Specs

go-openaudio is a single docker container that can be run on most hardware with a very minimal set up.

Stable releases are published monthly at openaudio/go-openaudio:stable.
Nightly (edge) builds are tagged by commit hash.
$AUDIO governance votes on adoption of versions. That version can be found here.

It is recommended to provision a VM with at least:

  • 16GB of memory
  • 8 cpu cores
  • 200GB boot disk
  • Datacenter-grade network access

Additionally, validator nodes require file storage. You may elect to use a disk, or any S3-compatible (elastic) blob storage. Generally blob-storage is substantially more cost-effective.

Set up

These instructions will show you a minimal docker compose set up with an auto-upgrade policy. You may choose your own path instead!

1. Provision a keypair

This is the Ethereum secp256k1 keypair for your node. This key never holds funds, but is used to sign requests.

pip install eth-keys
python -c "from eth_keys import keys;import os;p=keys.PrivateKey(os.urandom(32));print('delegateOwnerWallet=',p.public_key.to_checksum_address(),'\ndelegatePrivateKey=',p.to_hex(),sep='')"
2. Create an .env file
.env
nodeEndpoint=https://my-node.com
# The keypair you generated above
delegateOwnerWallet=0x01234567890abcdef01234567890abcdef012345
delegatePrivateKey=01234567890abcdef01234567890abcdef01234567890abcdef01234567890ab
# Your wallet address that is staking. If running an RPC, set to the same value as `delegateOwnerWallet`
spOwnerWallet=0x01234567890abcdef01234567890abcdef012345
 
# Validator storage configuration
# If electing to use blob storage, set:
OPENAUDIO_STORAGE_DRIVER_URL=s3://my-s3-bucket
AWS_REGION=us-west-2
AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
# If electing to use disk storage, to store blobs at `/data/storage`, set:
# OPENAUDIO_STORAGE_DRIVER_URL=file:///data/storage?no_tmp_dir=true
3. Create a docker compose file
docker-compose.yml
services:
  my-node:
    image: openaudio/go-openaudio:stable
    container_name: my-node
    env_file:
      - .env
    volumes:
      - /root/openaudio-prod-data:/data
    ports:
      - 80:80
      - 443:443
      - 26656:26656
 
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --cleanup --interval 3600 my-node
4. Run your node 
docker compose up -d
5. Monitor your node 
curl my-node.com/health-check

or visit https://my-node.com/console in your web browser

Blob storage options

Blob storage is configured using the popular go-cdk library and should work with most blob storage offerings on the market. We have provided some example config below to get started with some commonly used providers.

# AWS S3:
OPENAUDIO_STORAGE_DRIVER_URL=s3://my-s3-bucket
AWS_REGION=us-west-2
AWS_ACCESS_KEY_ID=XXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXX
 
# GCP Cloud Storage
#   you will need an additional mount for the credentials
#   i.e. `-v google-application-credentials.json:/tmp/google-application-credentials.json`
OPENAUDIO_STORAGE_DRIVER_URL=gs://my-gcs-bucket
GOOGLE_APPLICATION_CREDENTIALS=/tmp/google-application-credentials.json
 
# Cloudflare R2:
OPENAUDIO_STORAGE_DRIVER_URL='s3://my-r2-bucket?endpoint=https://abc123def456.r2.cloudflarestorage.com'
AWS_REGION=wnam
AWS_ACCESS_KEY_ID=XXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXX
 
# Vultr:
OPENAUDIO_STORAGE_DRIVER_URL='s3://my-vultr-bucket?endpoint=https://sjc1.vultrobjects.com'
AWS_REGION=sjc1
AWS_ACCESS_KEY_ID=XXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXX
 
# Digital Ocean Spaces:
#    Note: please delete your bucket name from the beginning of the https endpoint URL
OPENAUDIO_STORAGE_DRIVER_URL='s3://my-spaces-bucket?endpoint=https://sfo3.digitaloceanspaces.com'
AWS_REGION=sfo3
AWS_ACCESS_KEY_ID=XXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXX
 
# Backblaze B2:
OPENAUDIO_STORAGE_DRIVER_URL='s3://my-b2-bucket?endpoint=https://s3.us-west-004.backblazeb2.com'
AWS_REGION=us-west-004
AWS_ACCESS_KEY_ID=XXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXX

Moving to blob storage

To move from filesystem/disk storage to blob Storage

  1. Set the approprivate environment variables based on the above configuration for your provider.

  2. Set the env var

OPENAUDIO_STORAGE_DRIVER_URL_MOVE_FROM="file:///tmp/mediorum/blobs?no_tmp_dir=true"
  1. Restart your node.

You will see this log line:

info    Moving all files from file:///tmp/mediorum/blobs?no_tmp_dir=true to s3://my-s3-bucket. This may take a few hours...       
{"node": "https://my-node.com", "service": "mediorum"}

When finished, you will this log line:

info    Finished moving files between buckets. Please remove OPENAUDIO_STORAGE_DRIVER_URL_MOVE_FROM from your environment and restart the server. {"node": "https://my-node.com", "service": "mediorum"}

  1. When it completes, or when the target blob storage resembles the expected size, remove OPENAUDIO_STORAGE_DRIVER_URL_MOVE_FROM from your env.

  2. Restart your node. Any missed files will be re-synced by the mediorum repair job.

Node registration

A validator node can be registered as soon as it is stood up.

Currently the Audius Protocol Dashboard offers a simple UI to register nodes. You may also elect to use etherscan directly using the register function.

On the protocol dashboard:

  1. Connect a wallet or multisig using wallet connect button at the top of the page
  2. Click Nodes in the navigation menu
  3. Click Register New Node
  4. Fill out nodeEndpoint, delegateOwnerWallet based on your configuration above
  5. Set a desired stake amount (you must have this much $AUDIO already in your wallet)
  6. Click register and then sign & send the two transactions