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.

In this guide, you'll learn how to spin up a Moonbeam node using Systemd and how to maintain and purge your node.

If you're interested in compiling the binary yourself, which may take over 30 min and require 32GB of memory, you can check out the Manually Compile the Moonbeam Binary guide.

Checking Prerequisites¶

The following sections go through the process of using the binary and running a Moonbeam full node as a systemd service. To get started, you'll need to:

• Make sure you're running Ubuntu 18.04, 20.04, or 22.04. Moonbeam may work with other Linux flavors, but Ubuntu is currently the only tested version
• Make sure that your system meets the requirements. When connecting to Moonriver on Kusama or Moonbeam on Polkadot, it will take a few days to completely sync the embedded relay chain

Download the Latest Release Binary¶

To download the latest release binary, take the following steps:

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

   MoonbeamMoonriverMoonbase Alpha

   mkdir /var/lib/moonbeam-data
   

   mkdir /var/lib/moonriver-data
   

   mkdir /var/lib/alphanet-data
   

2. Use wget to grab the latest release binary and output it to the directory created in the previous step

   MoonbeamMoonriverMoonbase Alpha

   wget https://github.com/moonbeam-foundation/moonbeam/releases/download/v0.45.0/moonbeam \
   -O /var/lib/moonbeam-data/moonbeam
   

   wget https://github.com/moonbeam-foundation/moonbeam/releases/download/v0.45.0/moonbeam \
   -O /var/lib/moonriver-data/moonbeam
   

   wget https://github.com/moonbeam-foundation/moonbeam/releases/download/v0.45.0/moonbeam \
   -O /var/lib/alphanet-data/moonbeam
   

3. To verify that you have downloaded the correct version, you can run the following command in your terminal

   MoonbeamMoonriverMoonbase Alpha

   sha256sum /var/lib/moonbeam-data/moonbeam
   

   sha256sum /var/lib/moonriver-data/moonbeam
   

   sha256sum /var/lib/alphanet-data/moonbeam
   

   You should receive the following output:

   MoonbeamMoonriverMoonbase Alpha

   1f1f3a7ca52f28d9529a4bb01b4ee2ece6c9ed6b771f9a9763750650e7166bfb
   

   1f1f3a7ca52f28d9529a4bb01b4ee2ece6c9ed6b771f9a9763750650e7166bfb
   

   1f1f3a7ca52f28d9529a4bb01b4ee2ece6c9ed6b771f9a9763750650e7166bfb
   

Setup the Service¶

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

1. Create a service account to run the service

   MoonbeamMoonriverMoonbase Alpha

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

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

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

2. Ensure that you properly configure the ownership and permissions for the local directory housing the chain data, and also remember to grant execute permission to the binary file

   MoonbeamMoonriverMoonbase Alpha

   sudo chown -R moonbeam_service /var/lib/moonbeam-data
   sudo chmod +x /var/lib/moonbeam-data/moonbeam
   

   sudo chown -R moonriver_service /var/lib/moonriver-data
   sudo chmod +x /var/lib/moonriver-data/moonbeam
   

   sudo chown -R moonbase_service /var/lib/alphanet-data
   sudo chmod +x /var/lib/alphanet-data/moonbeam
   

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

First, you'll need to create a file named /etc/systemd/system/moonbeam.service to store the configurations.

Note that in the following start-up configurations, you have to:

• Replace INSERT_YOUR_NODE_NAME with your node name of choice. You'll have to do this in two places: one for the parachain and one for the relay chain
• Replace INSERT_RAM_IN_MB for 50% of the actual RAM your server has. For example, for 32GB of 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

For an overview of the flags used in the following start-up commands, plus additional commonly used flags, please refer to the Flags page of our documentation.

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 INSERT_RAM_IN_MB \
     --base-path /var/lib/moonbeam-data \
     --chain moonbeam \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
     --sync fast

[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 INSERT_RAM_IN_MB \
     --base-path /var/lib/moonriver-data \
     --chain moonriver \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
     --sync fast

[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 INSERT_RAM_IN_MB \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
     --sync fast

[Install]
WantedBy=multi-user.target

Allow External Access to Your Node¶

If you want to run an RPC endpoint, connect to Polkadot.js Apps, or run your own application, you can use the --unsafe-rpc-external flag to run the full node with external access to the RPC ports.

[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 INSERT_RAM_IN_MB \
     --base-path /var/lib/moonbeam-data \
     --chain moonbeam \
     --name "INSERT_YOUR_NODE_NAME" \
     --unsafe-rpc-external \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
     --sync fast

[Install]
WantedBy=multi-user.target

Use a SQL Backend for Frontier¶

The default Frontier database, which comes standard with Moonbeam nodes and contains all of the Ethereum-related elements, such as transactions, blocks, and logs, can be modified to use a SQL backend. Since eth_getLogs is a very resource-intensive method, the SQL backend aims to provide a more performant alternative for indexing and querying Ethereum logs in comparison to the default RocksDB database.

To spin up a node with a Frontier SQL backend, you'll need to add the --frontier-backend-type sql flag to your start-up command.

There are additional flags you can use to configure the pool size, query timeouts, and more for your SQL backend; please refer to the Flags page for more information.

[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 INSERT_RAM_IN_MB \
     --base-path /var/lib/moonbeam-data \
     --chain moonbeam \
     --name "INSERT_YOUR_NODE_NAME" \
     --frontier-backend-type sql \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
     --sync fast

[Install]
WantedBy=multi-user.target

Collator¶

Beginning with v0.39.0, new Moonbeam collator nodes will no longer generate session keys automatically on start-up. Nodes in existence prior to v0.39.0 do not need to make changes to how they handle session keys.

When setting up a new node, run the following command to generate and store on disk the session keys that will be referenced in the start-up command:

/var/lib/moonbeam-data/moonbeam key generate-node-key --base-path /var/lib/moonbeam-data --chain moonbeam && sudo chown -R moonbeam_service /var/lib/moonbeam-data

/var/lib/moonriver-data/moonbeam key generate-node-key --base-path /var/lib/moonriver-data --chain moonriver && sudo chown -R moonriver_service /var/lib/moonriver-data

/var/lib/alphanet-data/moonbeam key generate-node-key --base-path /var/lib/alphanet-data --chain alphanet  && sudo chown -R moonbase_service  /var/lib/alphanet-data

Now you can create the systemd configuration file:

[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 INSERT_RAM_IN_MB \
     --base-path /var/lib/moonbeam-data \
     --chain moonbeam \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
     --sync fast

[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 INSERT_RAM_IN_MB \
     --base-path /var/lib/moonriver-data \
     --chain moonriver \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
     --sync fast

[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 INSERT_RAM_IN_MB \
     --base-path /var/lib/alphanet-data \
     --chain alphanet \
     --name "INSERT_YOUR_NODE_NAME" \
     -- \
     --name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
     --sync fast

[Install]
WantedBy=multi-user.target

Run the Service¶

Register and start the service by running:

systemctl enable moonbeam.service
systemctl start moonbeam.service

And lastly, verify that the service is running:

systemctl status moonbeam.service

You can also check the logs by executing:

journalctl -f -u moonbeam.service

During the syncing process, you will see logs from both the embedded relay chain ([Relaychain]) and the parachain ([🌗]). These logs display a target block (live network state) and a best block (local node synced state).

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

systemctl stop moonbeam.service

Maintain Your Node¶

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

   MoonbeamMoonriverMoonbase Alpha

   rm /var/lib/moonbeam-data/moonbeam
   

   rm /var/lib/moonriver-data/moonbeam
   

   rm /var/lib/alphanet-data/moonbeam
   

3. Get the latest version of the Moonbeam release binary on GitHub and run the following command to update to that version

   MoonbeamMoonriverMoonbase Alpha

   wget https://github.com/moonbeam-foundation/moonbeam/releases/download/INSERT_NEW_VERSION_TAG/moonbeam \
   -O /var/lib/moonbeam-data/moonbeam
   

   wget https://github.com/moonbeam-foundation/moonbeam/releases/download/INSERT_NEW_VERSION_TAG/moonbeam \
   -O /var/lib/moonriver-data/moonbeam
   

   wget https://github.com/moonbeam-foundation/moonbeam/releases/download/INSERT_NEW_VERSION_TAG/moonbeam \
   -O /var/lib/alphanet-data/moonbeam
   

   Note

   If you compiled the binary manually, you'll need to move the binary from ./target/release/moonbeam to the data directory.

4. Update permissions

   MoonbeamMoonriverMoonbase Alpha

   chmod +x /var/lib/moonbeam-data/moonbeam
   chown moonbeam_service /var/lib/moonbeam-data/moonbeam
   

   chmod +x /var/lib/moonriver-data/moonbeam
   chown moonriver_service /var/lib/moonriver-data/moonbeam
   

   chmod +x /var/lib/alphanet-data/moonbeam
   chown moonbase_service /var/lib/alphanet-data/moonbeam
   

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

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 instructions in this guide. Make sure you are using the latest tag available, which you can find on the Moonbeam GitHub Release page.