Skip to main content

Migration Guide

Read this first

This portion of the guide is only for Node Operators that setup Audius Nodes using audius-docker-compose.

Overview​

Migrating Audius Nodes in just a few steps:

  1. Disable auto-upgrade on existing Audius Nodes
  2. Stop the Audius daemon on existing Audius Nodes
  3. Install audius-ctl
  4. Confirm your ssh access and port configuration
  5. Edit the configuration file
  6. Run your Audius Nodes

1. Disable Auto-Upgrade on Existing Nodes​

Disable Auto Upgrade by repeating these steps on each of you existing Audius Nodes

  1. ssh into Virtual Machine

  2. disable auto upgrade with the following command:

audius-cli auto-upgrade --remove

2. Stop the Audius daemon on Existing Nodes​

For each Node to be migrated, you will need to ssh into the Virtual Machine, disable auto upgrade, and down the Node. The workflow and required commands are as follows:

  1. ssh into Virtual Machine

  2. Down the Audius Node with the following command:

audius-cli down
No New Nodes

Existing Audius Nodes should be "upgraded in place", so unless you have a specific need, we strongly recommend following this guide and doing so.

If you are starting up a new Audius Node, follow the Installation Guide to get started.

3. Install audius-ctl​

Get started by opening a terminal on a local machine, this can be any computer, such as a laptop or desktop.

Run the following command to install the controller utility, audius-ctl

curl -sSL https://install.audius.org | sh
Where to install audius-ctl

While it is recommended to install the controller utility on a separate computer, such as your laptop, any machine can operate as a Controller. Check the Advanced Usage page for more information.

4. Confirm ssh Access to Audius Nodes​

For audius-ctl to interact with your Audius Nodes, your local machine will need ssh access.

Read more about configuring ssh access and port configuration here.

5. Edit the Configuration File​

Next you will need to edit the configuration file. Run the following command to get started:

audius-ctl config edit

5.1 Configuration Details​

The configuration file will be pre-populated with the required fields. Enter your information into each field for each Audius Node you will be running.

audius-ctl configuration file
network:
  deployOn: mainnet
nodes:
  content-1.example.com:        # <--- THE URL OF YOUR CONTENT NODE
    type: content
    privateKey: abc123          # <--- UNIQUE PRIV KEY USED BY THIS NODE TO SIGN RESPONSES
    wallet: 0xABC123            # <--- UNIQUE WALLET ADDRESS OF ABOVE PRIV KEY
    rewardsWallet: 0xABC123     # <--- ADDRESS OF WALLET HOLDING STAKED TOKENS
  discovery-1.example.com:      # <--- THE URL OF YOUR DISCOVERY NODE
    type: discovery
    privateKey: abc123          # <--- UNIQUE PRIV KEY USED BY THIS NODE TO SIGN RESPONSES
    wallet: 0xABC123            # <--- UNIQUE WALLET ADDRESS OF ABOVE PRIV KEY
    rewardsWallet: 0xABC123     # <--- ADDRESS OF WALLET HOLDING STAKED TOKENS
More Info
fielddescription
typeeither content or discovery
privateKeyprivate key associated with the wallet
walletAddress of wallet that contains no tokens but that is registered on chain, used to sign JSON responses from server
rewardsWalletWallet that registered (or will register) the Audius Node on chain

6. Run Your Audius Nodes​

With the configuration file setup correctly, the final command to run is:

audius-ctl up

This command does a few things:

  1. Loops over every Audius Node specified
  2. Connects to each Virtual Machine via ssh
    1. Checks that the required Audius Node software is installed
    2. If not found, runs the installer
    3. Starts the Audius Node

Additional Information​

Environment Variable Mapping​

Node Operators migrating existing Nodes will be familiar with the legacy variables for each Node type. See the mappings below to correctly use existing keys from a override.env file in a new configuration file.

  • Content Node Variables

    • delegateOwnerWallet --> wallet
    • delegatePrivateKey --> privateKey

  • Discovery Node Variables

    • audius_delegate_owner_wallet --> wallet
    • audius_delegate_private_key --> privateKey
Looking for Old Docs?

Please be aware that audius-docker-compose will soon no longer be supported.

Read the Migration Guide for instructions.

Click here for legacy documentation.

This guide describes how to run Audius services on a single machine via Docker Compose. The repository of Docker Compose files can be found on GitHub.

On a VM that meets the minimum requirements from above run:

bash <(curl https://raw.githubusercontent.com/AudiusProject/audius-docker-compose/main/install.sh)

During installation there will be prompts for required environment variables. The variables are:

Creator Node

  • creatorNodeEndpoint - The DNS of your content node. If you haven't registered the service yet, please enter the url you plan to register.
  • delegateOwnerWallet - Address of wallet that contains no tokens but that is registered on chain, used to sign JSON responses from server
  • delegatePrivateKey - Private key associated with delegateOwnerWallet
  • spOwnerWallet - Wallet that registered (or will register) the content node on chain

Discovery Node

  • audius_delegate_owner_wallet - Address of wallet that contains no tokens but that is registered on chain, used to sign JSON responses from server
  • audius_delegate_private_key - Private key associated with audius_delegate_owner_wallet