Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
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('OPENAUDIO_DELEGATE_WALLET=',p.public_key.to_checksum_address(),'\nOPENAUDIO_DELEGATE_PRIVATE_KEY=',p.to_hex(),sep='')"
2. Create an .env file
.env
OPENAUDIO_NODE_ENDPOINT=https://my-node.com
# The keypair you generated above
OPENAUDIO_DELEGATE_WALLET=0x01234567890abcdef01234567890abcdef012345
OPENAUDIO_DELEGATE_PRIVATE_KEY=01234567890abcdef01234567890abcdef01234567890abcdef01234567890ab
# Your wallet address that is staking. If running an RPC, set to the same value as `OPENAUDIO_DELEGATE_WALLET`
OPENAUDIO_OWNER_WALLET=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

Registration

Visit staking.openaudio.org to register your node.

  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 NODE ENDPOINT, NODE WALLET ADDRESS (delegate address) 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

Alternatively you can use etherscan directly using the register function or the Audius Protocol Dashboard.

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 Type and State Sync

By default, nodes run in a full configuration that prunes old blocks (≈1 week retained) and stores only this node's replication slice of blobs. That keeps disk usage bounded and is the right choice for most operators.

The following env vars opt your node into other configurations. See the Environment Variables reference for the full list.

OPENAUDIO_STORE_ALL

default: false Store every blob the network has, not just this node's replication slice. Used for backup / mirror nodes and is required to make use of OPENAUDIO_ARCHIVE_STORAGE_DRIVER_URL. Disk usage grows with the total network footprint.

OPENAUDIO_ARCHIVE

default: false Run in archival mode: never prune blocks. Required if you want to serve historical chain queries below the default retain window. Disk usage grows linearly with chain height.

OPENAUDIO_STATE_SYNC_SERVE_SNAPSHOTS

default: false Periodically produce CometBFT state-sync snapshots and serve them to bootstrapping peers. Turning this on helps the network — new nodes can sync from your snapshots instead of replaying from genesis — at the cost of extra disk for the retained snapshots (controlled by OPENAUDIO_STATE_SYNC_KEEP).