Install a node

Overview

This guide explains how to install the Algorand Node software on Linux distributions and Mac OS. When installing on Linux, two installation methods are covered: by package manager and by updater script.

The package manager method uses fixed directories and automatically updates. It has been validated on Debian, Ubuntu, Fedora, and CentOS.

The updater script method allows manually setting data directories and requires manual updates. It has been tested on the same Linux distributions from above, as well as on openSUSE Leap, Manjaro, Mageia, Alpine, and Solus.

Warning

Do not mix and match installation methods as this can lead to hard-to-debug issues. If the package manager method is available in your environment, we strongly recommend using only this method.

Tip

Windows users may choose to build their own native binaries. Rand Labs provides a repository with instructions on how to accomplish this, along with an accompanying tutorial.

Tip

If you are a developer and want to use a private network, AlgoKit is often simpler than installing a node manually. However, it is still recommended to install the Algorand software without running a node, to get access to the developer tools such as msgpacktool and algokey.

Hardware Requirements

(Last update to this section: April 3, 2024.)

Due to the higher TPS on MainNet, to successfully run an Algorand MainNet node, the following hardware is necessary:

• 8GB of RAM (Some node operators successfully use 4GB, but it requires additional memory management and may still lag behind during extremely high network activity)
• A not-too-slow SSD: HDD and SD cards are too slow for a MainNet node and will most likely prevent the node to sync
• at least 100Mbps connection (1Gbps recommended)

Participation nodes (especially those with high stake) and relays have higher requirements to ensure the performance of the overall blockchain.

Recommended system specification for participation nodes is:

• 8 vCPU
• 16 GB RAM
• 100 GB NVMe SSD or equivalent
• 1 Gbps connection with low latency

Recommended system specification for archival non-relay nodes is:

• 8 vCPU
• 16 GB RAM
• 3 TB SSD (blocks and catchpoint storage - ColdDataDir in the configuration file)
• 100 GB NVMe SSD (accounts - HotDataDir in the configuration file)
• 5 TB/month egress
• 1 Gbps connection with low latency

Recommended system specification for non-archival relay (aka light relay) nodes is:

• 16 vCPU
• 32 GB RAM
• 256 GB NVMe SSD or equivalent
• 30 TB/month egress
• 1 Gbps connection with very low latency

Recommended system specification for archival relay nodes is:

• 16 vCPU
• 32 GB RAM
• 3 TB SSD (blocks and catchpoint storage - ColdDataDir in the configuration file)
• 100 GB NVMe SSD (accounts - HotDataDir in the configuration file)
• 30 TB/month egress
• 1 Gbps connection with very low latency

While directly-attached NVMe SSD are recommended, in October 2022, the use of AWS EBS gp3 was able to provide sufficient performance. Users choosing this option should constantly monitor performance of the node, and may need to upgrade to faster storage solutions in the future (e.g., in case of important increase of TPS support).

Info

Private networks used for development require much lower specs as they are usually achieving much lower TPS. A Raspberry Pi with 2GB of RAM is sufficient for low-TPS private networks.

Docker Images

Official Docker images are available from Docker Hub.

Package manager installation overview

See Node Artifacts reference for a detailed list of some of files that are installed by this method. An environment variable can be set that points to the data directory and goal will use that variable if no -d flag is specified. The binaries will be installed in the /usr/bin and the data directory will be set to /var/lib/algorand. It is recommended to add to shell config files the following environment variable that points to the data directory:

export ALGORAND_DATA=/var/lib/algorand

Note that the environment variable set by this command is not permanent, so it is advisable to add the exports to shell config files (e.g., ~/.bashrc or ~/.zshrc).

Use this option when installing in the following operating systems: Debian, Ubuntu, Fedora, CentOS, and other Debian and Red Hat based Linux distributions.

Info

kmd related files such as the kmd token file will be written to the ${HOME}/.algorand/kmd-version directory. These files are primarily used with the SDKs and REST endpoints.

Updater script installation overview

A node installation consists of two folders: the binaries (bin) and the data (data) folders. The bin folder can be created anywhere, but Algorand recommends ~/node. This location is referenced later in the documentation. Remember to replace this location in the documentation below with the correct location. It is assumed that this folder is dedicated to Algorand binaries and is archived before each update. Note that nothing is currently deleted, the binaries for Algorand are just overwritten.

When installing for the first time a data directory will need to be specified. Algorand recommends using a location under the node folder, e.g. ~/node/data. See Node Artifacts reference for a detailed list of all files that are installed. An environment variable can be set that points to the data directory and goal will use that variable if no -d flag is specified.

Additionally, it is convenient to add ~/node to PATH so goal becomes directly executable, instead of having to constantly reference it as ./goal in the node directory.

export ALGORAND_DATA="$HOME/node/data"
export PATH="$HOME/node:$PATH"

Note that the environment variables set by these commands are not permanent, so it is advisable to add the exports to shell config files (e.g., ~/.bashrc or ~/.zshrc).

Use this option when installing in the following operating systems: macOS, openSUSE Leap, Manjaro, Mageia, Alpine, Solus, etc. Also, use this method for the Linux distributions listed in the previous section if you want full control of the installation process (this is not recommended for most users).

Installation with a package manager

This is the recommended method for most users on a compatible OS.

Debian based distributions (Debian, Ubuntu, Linux Mint, ...)

Nodes have been verified on Ubuntu 18.04 and 20.04, as well as on Debian 11. Other Debian-based distros should work as well (use apt-get install rather than apt install).

• Open a terminal and run the following commands.

sudo apt-get update
sudo apt-get install -y gnupg2 curl software-properties-common
curl -o - https://releases.algorand.com/key.pub | sudo tee /etc/apt/trusted.gpg.d/algorand.asc
sudo add-apt-repository "deb [arch=amd64] https://releases.algorand.com/deb/ stable main"
sudo apt-get update

# To get both algorand and the devtools:
sudo apt-get install -y algorand-devtools

# Or, to only install algorand:
sudo apt-get install -y algorand

algod -v

These commands will install and configure algod as a service and place the algorand binaries in the /usr/bin directory. These binaries will be in the path so the algod and goal commands can be executed from anywhere. Additionally, every node has a data directory, in this case, it will be set to /var/lib/algorand.

This install defaults to the Algorand MainNet network. See switching networks for details on changing to another network.

Note

Most tools are included in the node binary package and do not require a separate install. There are a few additional tools (such as pingpong) in a separate tools package (i.e., tools_stable_linux-amd64_2.1.6.tar.gz).

Note

Since the data directory /var/lib/algorand is owned by the user algorand and the daemon algod is run as the user algorand, some operations such as the ones related to wallets and accounts keys (goal account ... and goal wallet ...) need to be run as the user algorand. For example, to list participation keys, use

sudo -u algorand -E goal account listpartkeys

(assuming the environment variable $ALGORAND_DATA is set to /var/lib/algorand) or

sudo -u algorand -E goal account listpartkey -d /var/lib/algorand

(otherwise).

Warning

Never run goal as root (e.g., do not run sudo goal account listpartkeys). Running goal as root can compromise the permissions of files in /var/lib/algorand.

Red Hat based distributions (Fedora, CentOS, ...)

Installing on Fedora and CentOS are described below.

• To install to CentOS 7, open a terminal and run the following commands.

curl -O https://releases.algorand.com/rpm/rpm_algorand.pub
sudo rpmkeys --import rpm_algorand.pub
sudo yum install yum-utils
sudo yum-config-manager --add-repo https://releases.algorand.com/rpm/stable/algorand.repo

# To get both algorand and the devtools:
sudo yum install algorand-devtools

# Or, to only install algorand:
sudo yum install algorand

• To install to Fedora or CentOS 8 Stream, open a terminal and run the following commands.

curl -O https://releases.algorand.com/rpm/rpm_algorand.pub
sudo rpmkeys --import rpm_algorand.pub
dnf install -y 'dnf-command(config-manager)'
dnf config-manager --add-repo=https://releases.algorand.com/rpm/stable/algorand.repo
dnf install algorand

These commands will install and configure algod as a service and place the algorand binaries in the /usr/bin directory. These binaries will be in the path so the algod and goal commands can be executed from anywhere. Additionally, every node has a data directory, in this case, it will be set to /var/lib/algorand.

This install defaults to the Algorand MainNet network. See switching networks for details on changing to another network.

Note

Most tools are included in the node binary package and do not require a separate install. There are a few additional tools (such as pingpong) in a separate tools package (i.e., tools_stable_linux-amd64_2.1.6.tar.gz).

Installing the Devtools

Beginning with the 2.1.5 release, there is now a new package called algorand-devtools that contains the developer tools. The package contains the following binaries, some of which are new (as of 2.1.5) and some of which have been removed from the algorand package to decrease its size:

• carpenter
• catchupsrv
• msgpacktool
• tealcut
• tealdbg

Installing the devtools is simple and no additional entries need to be added for either apt or yum to be aware of them. Simply install the tools as usual via the respective package manager. Since the algorand package is a dependency of algorand-devtools and the two former cannot be older than the latter, one of two possible scenarios will occur upon downloading the devtools:

• If algorand has not been previously installed, it will automatically download it.
• If algorand is installed but older than the devtools, it will automatically upgrade it.

See the examples above to understand how to install the deb and rpm packages.

Start Node

Installs by a package manager automatically start the node. Starting and stopping a node should be done using systemctl commands:

sudo systemctl start algorand

sudo systemctl stop algorand

The status of the node can be checked by running:

goal node status -d /var/lib/algorand

Installation with the updater script

Installing on a Mac

Verified on OSX v12.3.1 (Monterey).

• Create a folder to hold the install package and files.

mkdir ~/node
cd ~/node

Download the updater script.

curl https://raw.githubusercontent.com/algorand/go-algorand/rel/stable/cmd/updater/update.sh -O

• Ensure that your system knows it's an executable file.

chmod 744 update.sh

• Run the installer from within your node directory.

./update.sh -i -c stable -p ~/node -d ~/node/data -n

When the installer runs, it will pull down the latest update package from S3 and install it. The -n option above tells the installer to not auto-start the node. If the installation succeeds the node will need to be started manually described later in this guide.

Info

When installing the rel/beta release, specify the beta channel -c beta

Info

Add the following exports to shell config files. Hereafter, goal will default to using $ALGORAND_DATA as the data directory, removing the need to specify -d ~/node/data in every command.

export ALGORAND_DATA="$HOME/node/data"
export PATH="$HOME/node:$PATH"

Note

If installing using the updater script then all the binaries are downloaded together, i.e., there is not a separate devtools archive file or package.

Installing on Linux

Nodes have been verified on Ubuntu, CentOS, Fedora, openSUSE Leap, Manjaro, Mageia, Alpine, and Solus. Other modern distros should work as well.

• Create a temporary folder to hold the install package and files.

mkdir ~/node
cd ~/node

Download the updater script.

wget https://raw.githubusercontent.com/algorand/go-algorand/rel/stable/cmd/updater/update.sh

• Ensure that your system knows it's an executable file.

chmod 744 update.sh

• Run the installer from within your node directory.

./update.sh -i -c stable -p ~/node -d ~/node/data -n

When the installer runs, it will pull down the latest update package from S3 and install it. The -n option above tells the installer to not auto-start the node. If the installation succeeds the node will need to be started manually described later in this guide.

Info

Add the following exports to shell config files. Hereafter, goal will default to using $ALGORAND_DATA as the data directory, removing the need to specify -d ~/node/data in every command.

export ALGORAND_DATA="$HOME/node/data"
export PATH="$HOME/node:$PATH"

Note

If installing using the updater script then all the binaries are downloaded together, i.e., there is not a separate devtools archive file or package.

Start Node

Installs by the updater script require that the node be started manually. This can be done with the following command:

goal node start

This will start the node and it can be verified by running:

pgrep algod

The node can be manually stopped by running:

goal node stop

Installing algod as a systemd service

When installing using the updater script, there are several shell scripts that are bundled into the tarball that will are helpful in running algod. One of those is the systemd-setup.sh script to create a system service.

Usage: ./systemd-setup.sh username group [bindir]

Note that this takes an optional binary directory (bindir) parameter. This will be discussed more in the following sections.

Installing system-wide

To install algod as a system-wide service, run the script with root privileges:

sudo ./systemd-setup.sh algorand algorand

This will create the service in /lib/systemd/system/[email protected] and will have used the template [email protected] (downloaded in the same tarball) to create the service. It includes a lot of helpful information at the top of the file and is worth perusing.

The location of the binaries is needed by the template to tell systemd where to find algod. This can be controlled by the bindir parameter, which is the third parameter when calling the shell script, and is expected to be an absolute path.

Here is a snippet of the template:

[Service]
ExecStart=@@BINDIR@@/algod -d %I
User=@@USER@@
Group=@@GROUP@@
...

Note

If bindir is not provided, the script will assume the current working directory.

After installing, the script will also make systemd aware that the script is present on the system. However, if making changes after installation, be sure to run the following command to register those changes:

sudo systemctl daemon-reload

All that's left now is to start the service using systemctl. If preferred, it can also be enabled to start on system startup.

sudo systemctl start algorand@$(systemd-escape $ALGORAND_DATA)

Configure Telemetry

Algod is instrumented to provide telemetry which is used for insight into the software's performance and usage. Telemetry is disabled by default and so no data will be shared with Algorand Inc. Enabling telemetry provides data to Algorand to improve the software and help to identify issues.

Enable Telemetry

Telemetry can be enabled by following the command below as the user running algod (replacing <name> with your desired hostname, e.g. 'SarahsLaptop'):

diagcfg telemetry name -n <name>

If the Debian package is used, the above command needs to be run as the algorand user, i.e.:

sudo -u algorand -H -E diagcfg telemetry name -n <name>

(The option -H is necessary to ensure $HOME is set to the home directory of the algorand user.)

Telemetry can also be provided without providing a hostname:

diagcfg telemetry enable

If the Debian package is used, the above command needs to be run as the algorand user, i.e.:

sudo -u algorand -H -E diagcfg telemetry enable

Note

After enabling (or disabling) telemetry, the node needs to be restarted.

Warning

Do not run diagcfg as the root user: it would only enable telemetry for nodes run as the root user (and nodes should usually not be run as the root user). In particular, do not run sudo diagcfg ....

Disable Telemetry

Telemetry can be disabled at any time by using (as the user running algod):

diagcfg telemetry disable

If the Debian package is used, the above command needs to be run as the algorand user, i.e.:

sudo -u algorand -H -E diagcfg telemetry

Technical Details and Checking Telemetry is Enabled

Running the diagcfg commands will create and update the logging configuration settings stored in ~/.algorand/logging.config (and data/logging.config if the parameter -d data is provided).

To check if telemetry is enabled, run (as the user running algod):

diagcfg telemetry

If the Debian package is used, the above command needs to be run as the algorand user, i.e.:

sudo -u algorand -H -E diagcfg telemetry

It is also possible to check whether algod is connected to the telemetry server by running:

sudo netstat -an | grep :9243

If a single node/algod is running and telemetry is enabled, the output should look like:

tcp        0      0 xxx.xxx.xxx.xxx:yyyyy        18.214.74.184:9243      ESTABLISHED

When telemetry is disabled, the above command prints nothing.

For additional detail see the reference page on telemetry.

Sync Node with Network

When a node first starts, it will need to sync with the network. This process can take a while as the node is loading up the current ledger and catching up to the rest of the network. See the section below a Fast Catchup option. The status can be checked by running the following goal command:

goal node status

The goal node status command will return information about the node and what block number it is currently processing. When the node is caught up with the rest of the network, the "Sync Time" will be 0.0 as in the example response below (if on MainNet, some details will be different).

Last committed block: 125064
Time since last block: 3.1s
Sync Time: 0.0s
Last consensus protocol: https://github.com/algorandfoundation/specs/tree/5615adc36bad610c7f165fa2967f4ecfa75125f0
Next consensus protocol: https://github.com/algorandfoundation/specs/tree/5615adc36bad610c7f165fa2967f4ecfa75125f0
Round for next consensus protocol: 125065
Next consensus protocol supported: true
Genesis ID: testnet-v1.0
Genesis hash: SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=

Sync Node Network using Fast Catchup

Fast Catchup is a new feature and will rapidly update a node using catchpoint snapshots. A new command on goal node is now available for catchup. The entire process should sync a node in minutes rather than hours or days. As an example, the results for a BetaNet fast catchup, at the time of writing this, was a couple minutes to get to the sync point and a few more minutes to sync the remaining blocks since the snapshot. The total blocks synced was around 4.2 million blocks and it finished syncing in under 6 minutes. Actual sync times may vary depending on the number of accounts, number of blocks and the network. Here are the links to get the most recent catchup point snapshot per network. The results include a round to catchup to and the provided catchpoint. Paste into the goal node catchup command.

BetaNet https://algorand-catchpoints.s3.us-east-2.amazonaws.com/channel/betanet/latest.catchpoint

TestNet https://algorand-catchpoints.s3.us-east-2.amazonaws.com/channel/testnet/latest.catchpoint

MainNet https://algorand-catchpoints.s3.us-east-2.amazonaws.com/channel/mainnet/latest.catchpoint

The results will look similar to this: 4420000#Q7T2RRTDIRTYESIXKAAFJYFQWG4A3WRA3JIUZVCJ3F4AQ2G2HZRA

Warning

Do NOT use fast catchup on an archival or relay node. If you ever do it, you need to reset your node and start from scratch.

Warning

Fast catchup requires trust in the entity providing the catchpoint. An attacker controlling enough relays and proposing a malicious catchpoint can in theory allow a node to sync to an incorrect state of the blockchain. For full decentralization and no trust requirement, either use a catchpoint generated by one of your archival node (you can read the catchpoint using goal node status) or catch up from scratch without fast catchup.

Steps:

1) Start the node, if not started already, and run a status.

goal node start

goal node status

Results should look something like this...

Last committed block: 308
Time since last block: 0.0s
Sync Time: 6.5s
Last consensus protocol: https://github.com/algorand/spec/tree/a26ed78ed8f834e2b9ccb6eb7d3ee9f629a6e622
Next consensus protocol: https://github.com/algorand/spec/tree/a26ed78ed8f834e2b9ccb6eb7d3ee9f629a6e622
Round for next consensus protocol: 309
Next consensus protocol supported: true
Last Catchpoint:
Genesis ID: betanet-v1.0
Genesis hash: mFgazF+2uRS1tMiL9dsj01hJGySEmPN28B/TjjvpVW0=

2) Use the sync point captured above and paste into the catchup option

goal node catchup 4420000#Q7T2RRTDIRTYESIXKAAFJYFQWG4A3WRA3JIUZVCJ3F4AQ2G2HZRA

3) Run another status and results should look something like this showing a Catchpoint status: goal node status

Results should show 5 Catchpoint status lines for Catchpoint, total accounts, accounts processed, total blocks , downloaded blocks.

Last committed block: 4453
Sync Time: 15.8s
Catchpoint: 4420000#Q7T2RRTDIRTYESIXKAAFJYFQWG4A3WRA3JIUZVCJ3F4AQ2G2HZRA
Catchpoint total accounts: 1146
Catchpoint accounts processed: 1146
Catchpoint total blocks: 1000
Catchpoint downloaded blocks: 81
Genesis ID: betanet-v1.0
Genesis hash: mFgazF+2uRS1tMiL9dsj01hJGySEmPN28B/TjjvpVW0=

Note

Only the first 3 status (Catchpoint, total accounts, accounts processed) will show right after catchup begins. Status on total blocks and downloaded blocks will only show after catchup processes the total number of accounts, which takes several minutes.

4) A new option can facilitate a status watch, -w which takes a parameter of time, in milliseconds, between two successive status updates. This will eliminate the need to repeatedly issue a status manually. Press ^c to exit the watch.

goal node status -w 1000

5) Notice that the 5 Catchpoint status lines will disappear when completed, and then only a few more minutes are needed to sync from that point to the current block. **Once there is a Sync Time of 0, the node is synced and if fully usable. **

Last committed block: 4431453
Time since last block: 3.9s
Sync Time: 0.0s
Last consensus protocol: https://github.com/algorandfoundation/specs/tree/e5f565421d720c6f75cdd186f7098495caf9101f
Next consensus protocol: https://github.com/algorandfoundation/specs/tree/e5f565421d720c6f75cdd186f7098495caf9101f
Round for next consensus protocol: 4431454
Next consensus protocol supported: true
Last Catchpoint: 4430000#UAQPNY32LP3K5ARGFUQEFTBGELI5ZAQOMBGE7YL5ZFXL2MXWTO2A
Genesis ID: betanet-v1.0
Genesis hash: mFgazF+2uRS1tMiL9dsj01hJGySEmPN28B/TjjvpVW0=

Troubleshooting for fast catchup

If fast catchup fails, check the following:

• the node is not archival (and is not a relay).
• the software is up-to-date: goal version -v should report the latest Algorand version in https://github.com/algorand/go-algorand/releases, ignoring the Algorand BetaNet releases.
• the catch point matches the network used by the node and reported as Genesis ID by goal node status.
• the hardware requirements above are satisfied, in particular a not-too-slow SSD is used.
• the computer does not run out of memory.

If you used fast catchup on an archival node, you need to stop the node, remove all files in the data folder except the configuration files (*.json) and the genesis files (genesis*), and restart the node. This operation will also remove all keys stored in the node. Proceed with caution.

Updating Node

The RPM or Debian packages are updated automatically. For other installs, check for and install the latest updates by running ./update.sh -d ~/node/data at any time from within your node directory. Note that the -d argument has to be specified when updating. It will query S3 for available builds and see if there are newer builds than the currently installed version. To force an update, run ./update.sh -i -c stable -d ~/node/data.

If there is a newer version, it will be downloaded and unpacked. The node will shutdown, the binaries and data files will be archived, and the new binaries will be installed. If any part of the process fails, the node will restore the previous version (bin and data) and restart the node. If it succeeds, the new version is started. The automatic start can be disabled by adding the -n option.

Setting up a schedule to automatically check for and install updates can be done with CRON.

crontab -e

Add a line that looks like this (run update.sh every hour, on the half-hour, of every day), where ‘user’ is the name of the account used to install / run the node:

30 * * * * /home/user/node/update.sh -d /home/user/node/data >/home/user/node/update.log 2>&1

DNS Configuration for betanet

For the betanet network, when installing a new node or relay, make the following modification to the config.json file located in the node's data directory. First, if there is not a config.json, make a copy of the config.json.example file.

cp config.json.example config.json

Then edit the config.json file and replace the line

"DNSBootstrapID": "<network>.algorand.network",

with

"DNSBootstrapID": "<network>.algodev.network",

This modification to the DNSBootstrapID is only required for the betanet network.