Skip to content

Run a Node on Moonbeam Using Systemd

Full Node Moonbeam Banner

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

Installation Instructions

This section goes 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/PureStake/moonbeam/releases/download/v0.15.1/moonbeam
wget https://github.com/PureStake/moonbeam/releases/download/v0.15.1/moonbeam

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

c08e5f55bfc1dc7e2eec47727f0e710bc112f64b04c96843874e2f22a9badcd6
c08e5f55bfc1dc7e2eec47727f0e710bc112f64b04c96843874e2f22a9badcd6

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.

First, let's start by cloning the moonbeam repo.

git clone https://github.com/PureStake/moonbeam
cd moonbeam

Let's check out the latest release:

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

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

Next, update your PATH environment variable by running:

source $HOME/.cargo/env

Lastly, build the parachain binary:

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.

Running the Systemd Service

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

First, let's create a service account to run the service:

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

Next, create a directory to store the binary and data. Make sure you set the ownership and permissions accordingly for the local directory that stores the chain data.:

mkdir /var/lib/alphanet-data
chown moonbase_service /var/lib/alphanet-data
mkdir /var/lib/moonriver-data
chown moonriver_service /var/lib/moonriver-data

Now, copy the binary built in the last section to the created folder. If you compiled the binary yourself, you'll need to copy the binary in the target directory (./target/release/moonbeam). Otherwise, copy the Moonbeam binary in the root:

cp ./moonbeam /var/lib/alphanet-data
cp ./moonbeam /var/lib/moonriver-data

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 YOUR-NODE-NAME in two different places
  • 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

Full Node

[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 \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --execution wasm \
     --wasm-execution compiled \
     --pruning=archive \
     --state-cache-size 1 \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "YOUR-NODE-NAME" \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="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 \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --execution wasm \
     --wasm-execution compiled \
     --pruning=archive \
     --state-cache-size 1 \
     --base-path /var/lib/moonriver-data \
     --chain moonriver \
     --name "YOUR-NODE-NAME" \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="YOUR-NODE-NAME (Embedded Relay)"

[Install]
WantedBy=multi-user.target

Collator

[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 \
     --validator \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --execution wasm \
     --wasm-execution compiled \
     --pruning=archive \
     --state-cache-size 1 \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "YOUR-NODE-NAME" \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="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 \
     --validator \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --execution wasm \
     --wasm-execution compiled \
     --pruning=archive \
     --state-cache-size 1 \
     --base-path /var/lib/moonriver-data \
     --chain moonriver \
     --name "YOUR-NODE-NAME" \
     -- \
     --port 30334 \
     --rpc-port 9934 \
     --ws-port 9945 \
     --pruning=archive \
     --name="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.

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

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
    
  2. Remove the old binary file:

    rm  /var/lib/alphanet-data/moonbeam
    
    rm  /var/lib/moonriver-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/PureStake/moonbeam/releases/download/<NEW VERSION TAG HERE>/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. Copy the binary to the data directory:

    # If you used the release binary:
    cp ./moonbeam /var/lib/alphanet-data
    
    # Or if you compiled the binary:
    cp ./target/release/moonbeam /var/lib/alphanet-data
    
    # If you used the release binary:
    cp ./moonbeam /var/lib/moonriver-data
    
    # Or if you compiled the binary:
    cp ./target/release/moonbeam /var/lib/moonriver-data
    
  6. Update permissions:

    chmod +x moonbeam
    chown moonbase_service moonbeam
    
    chmod +x moonbeam
    chown moonriver_service moonbeam
    
  7. Start your service:

    systemctl start moonbeam
    

To check the status of your updated node, you can run systemctl status moonbeam.service, or to see logs you can run journalctl -f -u moonbeam.service.

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/alphanet-data/*
sudo rm -rf /var/lib/moonriver-data/*

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

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

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

sudo rm -rf /var/lib/alphanet-data/polkadot/*
sudo rm -rf /var/lib/moonriver-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).