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
AUDIUS_STORAGE_DRIVER_URL=s3://my-s3-bucket
AWS_REGION=us-west-2
AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
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/audiusd-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 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:
AUDIUS_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`
AUDIUS_STORAGE_DRIVER_URL=gs://my-gcs-bucket
GOOGLE_APPLICATION_CREDENTIALS=/tmp/google-application-credentials.json
 
# Cloudflare R2:
AUDIUS_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:
AUDIUS_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
AUDIUS_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:
AUDIUS_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

AUDIUS_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 AUDIUS_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 AUDIUS_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

Migrating from an old stack

Discovery to validator

  1. Spin down your existing node
    If using audius-cli

    ssh <your-machine>
audius-cli down discovery-provider

    If using audius-ctl

    audius-ctl down discovery.host.com

  2. Follow the instructions above to create a new validator node

  3. Re-register your node

  1. Visit the Audius Protocol Dashboard
  2. Authenticate with your wallet
  3. Click on the node you wish to migrate
  4. Click the trash can icon to de-register the node, and type DEREGISTER to confirm
  5. Return to the nodes page of the Audius Protocol Dashboard
  6. Click register a new node
  7. Use the same URL and keypair you previously had used for your node

Content to validator

Existing content nodes, if running a recent audiusd or go-openaudio image, qualify as validator nodes. Content nodes have a smaller maximum stake allowance than validator nodes though, so it is beneficial to re-register them. It is also highly recommended that you move your node to blob storage if it is running off of a disk. See moving to blob storage.

To re-register your node:

Deregister your existing node
  1. Visit the Audius Protocol Dashboard
  2. Authenticate with your wallet
  3. Click on the node you wish to migrate
  4. Click the trash can icon to de-register the node, and type DEREGISTER to confirm
  5. Return to the nodes page of the Audius Protocol Dashboard
  6. Shut down your existing content node
Update node
  1. Update the environment variable creatorNodeEndpoint to be nodeEndpoint
  2. Set the image from audiusd to openaudio/go-openaudio:stable
Register the new node
  1. Click register a new node
  2. Use the same URL and keypair you previously had used for your node
  3. Spin your node back up