Installation

Already a Node Operator?

Do you currently run an Audius Node? Does audius-docker-compose sound familiar? If so, check out the 📦 Migration Guide to migrate your existing Audius Nodes to the new architecture.

Overview

Installing and managing Audius Nodes is (in most cases) a 4 step process.

Install audius-ctl
Confirm your ssh access and port configuration
Edit the configuration file
Run your Audius Nodes

1. 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.

2. 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.

3. Edit the Configuration File

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

audius-ctl config edit

3.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

field	description
`type`	either `content` or `discovery`
`privateKey`	private key associated with the `wallet`
`wallet`	Address of wallet that contains no tokens but that is registered on chain, used to sign JSON responses from server
`rewardsWallet`	Wallet that registered (or will register) the Audius Node on chain

Storage Configuration Options

Content Node Operators can use a variety of storage providers to best suite their needs. Read the Storage Configuration guide for more information.

4. 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:

Loops over every Audius Node specified
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

monitoring nodes

Verify Nodes are up and properly configured by using the audius-ctl status command.

Read more about the status command at the bottom of this page.

Useful Commands

`help` command

Get help, and view all of the available commands by running the following command:

audius-ctl --help

> audius-ctl --help
CLI for provisioning and interacting with audius nodes

Usage:
  audius-ctl [command] [flags]
  audius-ctl [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  config      view/modify audius-d configuration
  devnet      Spin up local ethereum, solana, and acdc chains for development
  down        Spin down nodes and network in the current context.
  help        Help about any command
  infra       Manage audius-d instances
  jump        Open a shell into the audius-d container running on a host.
  register    Register nodes on ethereum (only works for local devnet)
  restart     Fully turn down and then turn up audius-d.
  status      test audius-d connectivity
  statusbar   Run status bar [n/a]
  up          Spin up the audius nodes specified in your config, optionally specifying which hosts.

Flags:
      --debug     Print debug logs in console
  -h, --help      help for audius-ctl
  -v, --version   Display version info

Use "audius-ctl [command] --help" for more information about a command.

checkout the code on GitHub

`status` command

Check the status of all Audius Nodes from the command line

audius-ctl status

The example below shows a healthy content node and an unhealthy discovery node.

 NODE                     TYPE       UP     HEALTHY  CHAIN  WEBSOCKET  CLIENT IP  DB    DISK          UPTIME      COMMENT
 audius-cn1.example.com   content    true   true     n/a    n/a        matched    6 GB  1553/1938 GB  120h45m46s  <nil>
 audius-dn1.example.com   discovery  false  n/a      n/a    n/a        n/a        n/a   n/a           n/a         Unreachable after 2 retries
Error: One or more health checks failed

Status Field Descriptions

Field	Description	Example Values
`NODE`	name of the node
`TYPE`	node type	`content` or `discovery`
`UP`	is the node up	`true` or `false`
`HEALTHY`	is the node healthy	`true` or `false`
`CHAIN`	is chain in sync and is port `30300` accessible on Discovery Nodes	`healthy`, `unhealthy`
`WEBSOCKET`	are required ports open	`healthy`, `unreachable`
`CLIENT IP`	compare IP to what node sees	`matched`, `unmatched/error`
`DB`	size of the database	`90 GB`
`DISK`	storage disk usage and capacity	`1553/1938 GB`
`UPTIME`	node uptime	`120h45m46s`
`COMMENT`	additional information	`<nil>` indicates all is well

Overview​

1. Install audius-ctl​

2. Confirm ssh Access to Audius Nodes​

3. Edit the Configuration File​

3.1 Configuration Details​

4. Run Your Audius Nodes​

Useful Commands​

help command​

status command​