Manual Node Installation | Algorand Developer Portal

Manual Node Installation

This guide shows how to install and run an Algorand node on your system. It covers installation methods for both Linux distributions and MacOS, with Linux users having the option of package manager or updater script installation.

Installation Methods

There are two different methods for installing Algorand nodes depending on your operating system. Choose the approach that works for your platform and preferences.

Choose one installation method and stick with it. Mixing methods can lead to complex troubleshooting issues. If the package manager method is available for your Linux system, it is strongly recommended over the updater script method.

Package Manager Method

Supported on Debian-based (Ubuntu, Linux Mint) and Red Hat-based (Fedora, CentOS) distributions.

Recommended for users on supported Linux distributions. This method provides automated updates, a fixed directory structure, and a pre-configured system service, simplifying maintenance.

Install Algorand using your system package manager

Updater Script Method

Supported on Linux distributions and MacOS.

Required for MacOS users and supported for all Linux distributions. This method allows customizable data directory location. However, it uses a manual update process. It works with MacOS and all Linux distributions, including openSUSE Leap, Manjaro, Mageia, Alpine, and Solus.

Alternative Options

Docker

Official Docker images are available from Docker Hub.

Windows

You can build native binaries using Rand Labs’ repository or use a third-party tool like FUNC.

Development

If you need a private network for development, consider using AlgoKit for a simpler setup. Even without running a node, installing Algorand software provides access to essential developer tools such as msgpacktool and algokey, along with other development utilities.

Package Manager Installation

The package manager installs Algorand node software in the standard system locations:

See Node Artifacts for a complete list of installed files.

It is recommended to configure the environment by adding to your shell config file (~/.bashrc or ~/.zshrc):

export ALGORAND_DATA=/var/lib/algorand

This sets a permanent environment variable that tells Algorand tools where to find your node’s data directory, eliminating the need to specify it with the -d flag in every command.

Installation

For Debian-Based Systems (Ubuntu, Linux Mint)

  1. First, update your system and install required packages:
sudo apt-get update
sudo apt-get install -y gnupg2 curl software-properties-common
  1. Add Algorand’s repository and security key:
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
  1. Install Algorand (choose one option):
# Option A: Install Algorand with developer tools
sudo apt-get install -y algorand-devtools

# Option B: Install only Algorand node
sudo apt-get install -y algorand

For Red Hat-Based Systems (Fedora, CentOS)

CentOS 7
  1. Import Algorand’s repository key and set up the repository:
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
  1. Install Algorand (choose one option):
# Option A: Install Algorand with developer tools
sudo yum install algorand-devtools

# Option B: Install only Algorand node
sudo yum install algorand
Fedora or CentOS 8 Stream
  1. Import Algorand’s repository key and set up the repository:
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
  1. Install Algorand:
dnf install algorand

Post-Installation Notes

After installation, Algorand is configured as a system service and starts automatically on MainNet. See switching networks for details on changing to another network.

All core binaries are installed in /usr/bin, so you can run algod and goal commands from any directory. Your node’s data will be stored in /var/lib/algorand.

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

# If $ALGORAND_DATA is set:

sudo -u algorand -E goal account listpartkeys

# If $ALGORAND_DATA is not set:

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

Additional tools are available through separate packages:

Installing the Developer Tools

The algorand-devtools package (introduced in version 2.1.5) provides additional developer utilities:

Installation is straightforward using your system’s package manager (apt or yum). The package manager will handle dependencies automatically:

See the installation instructions above for detailed installation commands.

Managing Your Node

The node starts automatically after package manager installation. To control the node manually, use the following commands:

To start your node:

sudo systemctl start algorand

To stop your node:

sudo systemctl stop algorand

To check your node’s status:

goal node status -d /var/lib/algorand

Updater Script Installation

The updater script installation requires two main directories:

When updating, the script archives your existing installation before overwriting the binaries. Configure your environment by adding to your shell config file (~/.bashrc or ~/.zshrc):

export ALGORAND_DATA="$HOME/node/data"

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

MacOS Installation

Verified on OSX v12.3.1 (Monterey).

  1. Create and enter the installation directory:
mkdir ~/node

cd ~/node
  1. Download and prepare the updater script:
curl https://raw.githubusercontent.com/algorand/go-algorand/rel/stable/cmd/updater/update.sh -O

chmod 744 update.sh
  1. Run the installer:
./update.sh -i -c stable -p ~/node -d ~/node/data -n

For beta releases, use -c beta instead of -c stable.

Running the Node as a macOS Service

This section outlines the basic steps to install prerequisites, create a launch service (.plist), and keep your Algorand node running automatically on macOS.

  1. Initial Setup tasks

    1. Install Homebrew
      Visit Homebrew’s official site for installation instructions.

    2. Install bash 

      brew install bash

    3. (Optional) Install Netdata
      Netdata helps monitor system metrics in real time. 

      brew install netdata

    4. Disable Sleep
      To prevent macOS from suspending your node, you can disable sleep targets: 

      sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target
  2. Creating the Managed Service Create a .plist file to automatically start and manage algod on macOS. Below is an example; adjust paths as necessary:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.algorand</string>
<key>Program</key>
<string>/Users/USERNAME/node/algod</string>
<key>EnvironmentVariables</key>
<dict>
<key>ALGORAND_DATA</key>
<string>/Users/USERNAME/node/data</string>
</dict>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<dict>
<key>SuccessfulExit</key>
<false/>
<key>Crashed</key>
<true/>
</dict>
<key>ThrottleInterval</key>
<integer>5</integer>
</dict>
</plist>

......(continues with other instructions as per the original markdown)......

Synchronizing Your Node

After starting your node for the first time, it needs to synchronize with the network by downloading and validating the blockchain. There are two methods for this:

Standard Synchronization

When using standard synchronization, your node downloads and validates every block since genesis. This process can take several hours or even days, depending on your hardware and network connection.

To check your node’s sync status:

goal node status

Fast Catchup

Fast catchup significantly accelerates the synchronization process by using catchpoint snapshots. Instead of processing every block, your node downloads a recent snapshot of the blockchain state and then synchronizes only the most recent blocks.

However, keep in mind that fast-catchup requires trusting the entity providing the catchpoint. For maximum security, either use a catchpoint from your own archiver node or synchronize from genesis.

Enabling Telemetry

Algorand nodes include telemetry instrumentation that can provide insights into the software’s performance and usage. This data helps Algorand Inc. improve the software and identify issues. Telemetry is disabled by default - no data will be shared unless you explicitly enable it.

Managing Telemetry

Enable Telemetry

To enable telemetry with or without a custom hostname, use:

diagcfg telemetry name -n <hostname>

Replace <hostname> with your desired identifier (e.g., ‘MainNetRepeater1’ or ‘TestNetNode2’).

Disable Telemetry

To disable telemetry:

diagcfg telemetry disable

Verifying Telemetry Status

To verify your telemetry settings:

diagcfg telemetry

Technical Details

Third-Party Telemetry Services

In addition to Algorand’s default telemetry service, you can send your node’s telemetry data to third-party services like Nodely, providing additional features for monitoring.