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.
-
Clone the Moonbeam repo
git clone https://github.com/moonbeam-foundation/moonbeam cd moonbeam
-
Check out to 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
-
Update your
PATH
environment variable by running:source $HOME/.cargo/env
-
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
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.
-
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
-
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
-
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
-
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 to16000
. The minimum value is2000
, 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
You can also check the logs by executing:
journalctl -f -u moonbeam.service
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:
-
Stop the systemd service:
sudo systemctl stop moonbeam.service
-
Remove the old binary file:
rm /var/lib/moonbeam-data/moonbeam
rm /var/lib/moonriver-data/moonbeam
rm /var/lib/alphanet-data/moonbeam
-
Get the latest version of Moonbeam from the Moonbeam GitHub Release page
-
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. -
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
-
Update permissions:
chmod +x moonbeam chown moonbeam_service moonbeam
chmod +x moonbeam chown moonriver_service moonbeam
chmod +x moonbeam chown moonbase_service moonbeam
-
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).
| Created: November 17, 2021