Skip to content

Run a Node on Moonbeam Using Systemd

Introduction

Running a full node on a Moonbeam-based network allows you to connect to the network, sync with a bootnode, obtain local access to RPC endpoints, author blocks on the parachain, and more.

This guide is meant for people with experience compiling Substrate based blockchain nodes. A parachain node is similar to a typical Substrate node, but there are some differences. A Substrate parachain node will be a bigger build because it contains code to run the parachain itself, as well as code to sync the relay chain, and facilitate communication between the two. As such, this build is quite large and may take over 30 min and require 32GB of memory.

Note

Moonbase Alpha is still considered an Alphanet, and as such will not have 100% uptime. The parachain might be purged as needed. During the development of your application, make sure you implement a method to redeploy your contracts and accounts to a fresh parachain quickly. If a chain purge is required, it will be announced via our Discord channel at least 24 hours in advance.

Getting Started

The following sections go through the process of using the binary and running a Moonbeam full node as a systemd service. The following steps were tested on an Ubuntu 18.04 installation. Moonbeam may work with other Linux flavors, but Ubuntu is currently the only tested version.

To get started quickly without the hassle of compiling the binary yourself, you can use The Release Binary. Or if you prefer to manually build the binaries yourself, which could take around 30 minutes to install the dependencies and compile, you can check out the Compile the Binary section.

The Release Binary

To get started use wget to grab the latest release binary:

wget https://github.com/moonbeam-foundation/moonbeam/releases/download/v0.33.0/moonbeam

wget https://github.com/moonbeam-foundation/moonbeam/releases/download/v0.33.0/moonbeam

wget https://github.com/moonbeam-foundation/moonbeam/releases/download/v0.33.0/moonbeam

To verify that you have downloaded the correct version, you can run sha256sum moonbeam in your terminal, you should receive the following output:

1a31ee40cc2e320a009ee687624c53bb51cf65c69a0409b018a5378d5231eaf7

1a31ee40cc2e320a009ee687624c53bb51cf65c69a0409b018a5378d5231eaf7

1a31ee40cc2e320a009ee687624c53bb51cf65c69a0409b018a5378d5231eaf7

Once you've retrieved the binary, you can skip ahead to the Running the Systemd Service section to get started running your node.

Compile the Binary

Manually compiling the binary can take around 30 minutes and requires 32GB of memory.

The following commands will build the latest release of the Moonbeam parachain.

  1. Clone the Moonbeam repo

    git clone https://github.com/moonbeam-foundation/moonbeam
cd moonbeam

  2. Check out to the latest release:

    git checkout tags/$(git describe --tags)

  3. If you already have Rust installed, you can skip the next two steps. Otherwise, install Rust and its prerequisites via Rust's recommended method by executing:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

  4. Update your PATH environment variable by running:

    source $HOME/.cargo/env

  5. Build the parachain binary:

    Note

    If you are using Ubuntu 20.04 or 22.04, then you will need to install these additional dependencies before building the binary:

    apt install clang protobuf-compiler libprotobuf-dev -y 

    cargo build --release

Compiling Binary

If a cargo not found error shows up in the terminal, manually add Rust to your system path or restart your system:

source $HOME/.cargo/env

Now you can use the Moonbeam binary to run a systemd service.

Setup the Service

The following commands will set up everything regarding running the service.

  1. Create a service account to run the service:

    adduser moonbeam_service --system --no-create-home

    adduser moonriver_service --system --no-create-home

    adduser moonbase_service --system --no-create-home

  2. Create a directory to store the binary and data (you might need sudo):

    mkdir /var/lib/moonbeam-data

    mkdir /var/lib/moonriver-data

    mkdir /var/lib/alphanet-data

  3. Move the binary built in the last section to the created folder. If you compiled the binary yourself, you'll need to move the binary in the target directory (./target/release/). Otherwise, move the Moonbeam binary in the root (you might need sudo):

    mv ./moonbeam /var/lib/moonbeam-data

    mv ./moonbeam /var/lib/moonriver-data

    mv ./moonbeam /var/lib/alphanet-data

  4. Make sure you set the ownership and permissions accordingly for the local directory that stores the chain data:

    sudo chown -R moonbeam_service /var/lib/moonbeam-data

    sudo chown -R moonriver_service /var/lib/moonriver-data

    sudo chown -R moonbase_service /var/lib/alphanet-data

Create the Configuration File

The next step is to create the systemd configuration file. If you are setting up a collator node, make sure to follow the code snippets for Collator. Note that you have to:

  • Replace INSERT_YOUR_NODE_NAME in two different places
  • Replace <50% RAM in MB> for 50% of the actual RAM your server has. For example, for 32 GB RAM, the value must be set to 16000. The minimum value is 2000, but it is below the recommended specs
  • Double-check that the binary is in the proper path as described below (ExecStart)
  • Double-check the base path if you've used a different directory
  • Name the file /etc/systemd/system/moonbeam.service

Note

For client versions prior to v0.30.0, --rpc-port was used to specify the port for HTTP connections, and --ws-port was used to specify the port for WS connections. As of client v0.30.0, these flags have been combined, and the default port for the --ws-port flag, which is 9944, is used for both HTTP and WS connections. The maximum number of connections to that port has been hardcoded to 100 and could be modified with the --ws-max-connections flag.

As of client v0.33.0, the --ws-port and --ws-max-connections flags have been deprecated and removed in favor of the --rpc-port and --rpc-max-connections flags. The default port is still 9944, and the default maximum number of connections is still set to 100.

Full Node

[Unit]
Description="Moonbeam systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonbeam_service
SyslogIdentifier=moonbeam
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/moonbeam-data/moonbeam \
     --state-pruning=archive \
     --trie-cache-size 1073741824 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/moonbeam-data \
     --chain moonbeam \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

[Unit]
Description="Moonriver systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonriver_service
SyslogIdentifier=moonriver
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/moonriver-data/moonbeam \
     --state-pruning=archive \
     --trie-cache-size 1073741824 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/moonriver-data \
     --chain moonriver \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

[Unit]
Description="Moonbase Alpha systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonbase_service
SyslogIdentifier=moonbase
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/alphanet-data/moonbeam \
     --state-pruning=archive \
     --trie-cache-size 1073741824 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Note

If you want to run an RPC endpoint, to connect Polkadot.js Apps, or to run your own application, use the --unsafe-rpc-external flag to run the full node with external access to the RPC ports. More details are available by running moonbeam --help. This is not recommended for Collators. For an overview of the available flags, please refer to the Flags page of our documentation.

Collator

[Unit]
Description="Moonbeam systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonbeam_service
SyslogIdentifier=moonbeam
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/moonbeam-data/moonbeam \
     --collator \
     --trie-cache-size 1073741824 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/moonbeam-data \
     --chain moonbeam \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

[Unit]
Description="Moonriver systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonriver_service
SyslogIdentifier=moonriver
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/moonriver-data/moonbeam \
     --collator \
     --trie-cache-size 1073741824 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/moonriver-data \
     --chain moonriver \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

[Unit]
Description="Moonbase Alpha systemd service"
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=10
User=moonbase_service
SyslogIdentifier=moonbase
SyslogFacility=local7
KillSignal=SIGHUP
ExecStart=/var/lib/alphanet-data/moonbeam \
     --collator \
     --trie-cache-size 1073741824 \
     --db-cache <50% RAM in MB> \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Note

You can specify a custom Prometheus port with the --prometheus-port XXXX flag (replacing XXXX with the actual port number). This is possible for both the parachain and embedded relay chain.

Run the Service

Almost there! Register and start the service by running:

systemctl enable moonbeam.service
systemctl start moonbeam.service

And lastly, verify the service is running:

systemctl status moonbeam.service

Service Status

You can also check the logs by executing:

journalctl -f -u moonbeam.service

Service Logs

If you need to stop the service for any reason, you can run:

systemctl stop moonbeam.service

Update the Client

As Moonbeam development continues, it will sometimes be necessary to upgrade your node software. Node operators will be notified on our Discord channel when upgrades are available and whether they are necessary (some client upgrades are optional). The upgrade process is straightforward and is the same for a full node or collator.

If you want to update your client, you can keep your existing chain data in tact, and only update the binary by following these steps:

  1. Stop the systemd service:

    sudo systemctl stop moonbeam.service

  2. Remove the old binary file:

    rm  /var/lib/moonbeam-data/moonbeam

    rm  /var/lib/moonriver-data/moonbeam

    rm  /var/lib/alphanet-data/moonbeam

  3. Get the latest version of Moonbeam from the Moonbeam GitHub Release page

  4. If you're using the release binary, update the version and run:

    wget https://github.com/moonbeam-foundation/moonbeam/releases/download/INSERT_NEW_VERSION_TAG/moonbeam

    If you want to compile the binary, please refer back to the Compile the Binary instructions, making sure you git checkout to the latest version.

  5. Move the binary to the data directory:

    # If you used the release binary:
mv ./moonbeam /var/lib/moonbeam-data

# Or if you compiled the binary:
mv ./target/release/moonbeam /var/lib/moonbeam-data

    # If you used the release binary:
mv ./moonbeam /var/lib/moonriver-data

# Or if you compiled the binary:
mv ./target/release/moonbeam /var/lib/moonriver-data

    # If you used the release binary:
mv ./moonbeam /var/lib/alphanet-data

# Or if you compiled the binary:
mv ./target/release/moonbeam /var/lib/alphanet-data

  6. Update permissions:

    chmod +x moonbeam
chown moonbeam_service moonbeam

    chmod +x moonbeam
chown moonriver_service moonbeam

    chmod +x moonbeam
chown moonbase_service moonbeam

  7. Start your service:

    systemctl start moonbeam.service

To check the status of the service and/or logs, you can refer to the commands from before.

Purge Your Node

If you need a fresh instance of your Moonbeam node, you can purge your node by removing the associated data directory.

Depending on whether you used the release binary or compiled the binary yourself, the instructions for purging your chain data will slightly vary. If you compiled the binary yourself, you can skip ahead to the Purge Compiled Binary section.

Purge Release Binary

You'll first need to stop the systemd service:

sudo systemctl stop moonbeam

To purge your parachain and relay chain data, you can run the following command:

sudo rm -rf /var/lib/moonbeam-data/*

sudo rm -rf /var/lib/moonriver-data/*

sudo rm -rf /var/lib/alphanet-data/*

To only remove the parachain data for a specific chain, you can run:

sudo rm -rf /var/lib/moonbeam-data/chains/*

sudo rm -rf /var/lib/moonriver-data/chains/*

sudo rm -rf /var/lib/alphanet-data/chains/*

Similarly, to only remove the relay chain data, you can run:

sudo rm -rf /var/lib/moonbeam-data/polkadot/*

sudo rm -rf /var/lib/moonriver-data/polkadot/*

sudo rm -rf /var/lib/alphanet-data/polkadot/*

Now that your chain data has been purged, you can start a new node with a fresh data directory. You can install the newest version by repeating the Installation Instructions. Make sure you are using the latest tag available, which you can find on the Moonbeam GitHub Release page.

Note

On an as-needed basis, Moonbase Alpha might be purged and reset. In these instances, you will need to purge both the parachain data and the relay chain data. If a purge is required, node operators will be notified in advance (via our Discord channel).

Purge Compiled Binary

If you want to start a fresh instance of a node, there are a handful of purge-chain commands available to you which will remove your previous chain data as specified. The base command which will remove both the parachain and relay chain data is:

./target/release/moonbeam purge-chain

You can add the following flags to the above command if you want to specify what data should be purged:

  • --parachain - only deletes the parachain database, keeping the relay chain data in tact
  • --relaychain - only deletes the relay chain database, keeping the parachain data in tact

You can also specify a chain to be removed:

  • --chain - specify the chain using either one of the predefined chains or a path to a file with the chainspec

To purge only your Moonbase Alpha parachain data, for example, you would run the following command:

./target/release/moonbeam purge-chain --parachain --chain alphanet

To specify a path to the chainspec for a development chain to be purged, you would run:

./target/release/moonbeam purge-chain --chain example-moonbeam-dev-service.json

For the complete list of available purge-chain commands, you can access the help menu by running:

./target/release/moonbeam purge-chain --help

Now that your chain data has been purged, you can start a new node with a fresh data directory. You can install the newest version by repeating the Installation Instructions. Make sure you are using the latest tag available, which you can find on the Moonbeam GitHub Release page.

Note

On an as-needed basis, Moonbase Alpha might be purged and reset. In these instances, you will need to purge both the parachain data and the relay chain data. If a purge is required, node operators will be notified in advance (via our Discord channel).

Last update: September 22, 2023
| Created: November 17, 2021