Run a Node on Moonbeam¶

Introduction¶

With the release of Moonbase Alpha v6, you can spin up a node that connects to the Moonbase Alpha TestNet, syncs with a bootnode, provides local access your RPC endpoints, and even authors blocks on the parachain.

In our TestNet, the relay chain is hosted and run by PureStake. But as development progresses, there will also be deployments in Kusama and then Polkadot. Here's how we will name these upcoming environments and their corresponding chain specification files name:

Network	Hosted By	Chain Name
Moonbase Alpha	PureStake	alphanet
Moonriver	Kusama	not available
Moonbeam	Polkadot	not available

This guide is meant for people with experience running Substrate based chains. Running a parachain is similar to running a Substrate node with a few differences. A Substrate parachain node will run two processes: one to sync the relay chain and one to sync the parachain. As such, many things are doubled, for example, the database directory, the ports used, the log lines, and more.

Note

Moonbase Alpha is still considered an Alphanet, and as such will not have 100% uptime. We will be purging the parachain from time to time. During the development of your application, make sure you implement a method to redeploy your contracts and accounts to a fresh parachain quickly. We will announce when a chain purge will take place via our Discord channel at least 24 hours in advance.

Requirements¶

The minimum specs recommended to run a node are shown in the following table. For our Kusama and Polkadot MainNet deployments, disk requirements will be higher as the network grows.

Component		Requirement
CPU		8 Cores (early development phase - not optimized yet)
RAM		16 GB (early development phase - not optimized yet)
SSD		50 GB (to start in our TestNet)
Firewall		P2P port must be open to incoming traffic: - Source: Any - Destination: 30333, 30334 TCP

Note

If you don't see an Imported message (without the [Relaychain] tag) when running a node, you might need to double-check your port configuration.

Running Ports¶

As stated before, the relay/parachain nodes will listen on multiple ports. The default Substrate ports are used in the parachain, while the relay chain will listen on the next higher port.

The only ports that need to be open for incoming traffic are those designated for P2P.

Default Ports for a Parachain Full-Node¶

Description		Port
P2P		30333 (TCP)
RPC		9933
WS		9944
Prometheus		9615

Default Ports of Embedded Relay Chain¶

Description		Port
P2P		30334 (TCP)
RPC		9934
WS		9945
Prometheus		9616

Installation Instructions - Docker¶

A Moonbase Alpha node can be spun up quickly using Docker. For more information on installing Docker, please visit this page. At the time of writing, the Docker version used was 19.03.6.

First, we need to create a local directory to store the chain data and set the necessary permissions:

mkdir /var/lib/alphanet-data

Note

Make sure you set the ownership and permissions accordingly for the local directory that stores the chain data using the chown and chmod commands.

Now we can execute the docker run command. Note that you have to: - Replace YOUR-NODE-NAME in two different places. - For collators, replace PUBLIC_KEY with the public address that will be associated with collation activities.

Note

If you are setting up a collator node, make sure to follow the code snippets for "Collator".

Full Node

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
purestake/moonbeam:v0.6.1 \
--base-path=/data \
--chain alphanet \
--name="YOUR-NODE-NAME" \
--execution wasm \
--wasm-execution compiled \
-- \
--name="YOUR-NODE-NAME (Embedded Relay)"

Collator

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
purestake/moonbeam:v0.6.1 \
--base-path=/data \
--chain alphanet \
--name="YOUR-NODE-NAME" \
--collator \
--author-id PUBLIC_KEY \
--execution wasm \
--wasm-execution compiled \
-- \
--name="YOUR-NODE-NAME (Embedded Relay)"

Once Docker pulls the necessary images, your Moonbase Alpha full node will start, displaying lots of information, such as the chain specification, node name, role, genesis state, and more:

Full Node Starting

Note

Running telemetry is not mandatory for full nodes, only collators. You can add the flag --no-telemetry to run the full node without telemetry activated.

The command above will enable all exposed ports, including the P2P, RPC, and Prometheus (telemetry) ports. This command is compatible to use with the Gantree Node Watchdog telemetry. If you want to expose specific ports, enable those on the Docker run command line as shown below. However, doing so will block the Gantree Node Watchdog (telemetry) container from accessing the moonbeam container, so don't do this when running a collator unless you understand docker networking.

docker run -p 30334:30334 -p 30333:30333 -p 9933:9933 -p 9944:9944 #rest of code goes here

During the syncing process, you will see messages from both the embedded relay chain and the parachain (without a tag). These messages display a target block (TestNet) and a best block (local node synced state).

Full Node Starting

Once synced, you have a node of the Moonbase Alpha TestNet running locally!

Installation Instructions - Binary¶

In this section, we'll go through the process of compiling the binary and running a Moonbeam full node as a systemd service. The following steps were tested on an Ubuntu 18.04 installation. Moonbase Alpha may work with other Linux flavors, but Ubuntu is currently the only tested version.

Compiling the Binary¶

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 tag | tail -1)

Next, install Substrate and all its prerequisites, including Rust, by executing:

curl https://getsubstrate.io -sSf | bash -s -- --fast

Now, we need to make some checks (correct version of Rust nightly) with the initialization script:

./scripts/init.sh

Lastly, let's build parachain binary:

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

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

Next, we need to create a directory to store the binary and data. We'll also set the necessary permissions:

mkdir /var/lib/alphanet-data
chmod 0755 /var/lib/alphanet-data
chown moonbase_service /var/lib/alphanet-data

Now, we need to copy the binary we built in the last section to the created folder:

cp ./target/release/moonbeam /var/lib/alphanet-data

The next step is to create the systemd configuration file. 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
For collators, replace PUBLIC-KEY with the public key of your H160 Ethereum address created above
Name the file /etc/systemd/system/moonbeam.service

Note

If you are setting up a collator node, make sure to follow the code snippets for "Collator".

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 \
     --parachain-id 1000 \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --pruning=archive \
     --unsafe-rpc-external \
     --unsafe-ws-external \
     --rpc-methods=Safe \
     --rpc-cors all \
     --log rpc=info \
     --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

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 \
     --parachain-id 1000 \
     --collator \
     --author-id PUBLIC_KEY \
     --port 30333 \
     --rpc-port 9933 \
     --ws-port 9944 \
     --pruning=archive \
     --unsafe-rpc-external \
     --unsafe-ws-external \
     --rpc-methods=Safe \
     --rpc-cors all \
     --log rpc=info \
     --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

Note

Running telemetry is not mandatory for full nodes. You can add the flag --no-telemetry to run the full node without telemetry activated.

We are almost there! We need to 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

We can also check the logs by executing:

journalctl -f -u moonbeam.service

Service Logs

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

First, stop the docker container or systemd service:

sudo docker stop `CONTAINER_ID`
# or
sudo systemctl stop moonbeam

Then, install the new version by repeating the steps described before, making sure that you are using the latest tag available. After updating, you can start the service again.

Purging the Chain¶

Occasionally Moonbase Alpha might be purged and reset around major upgrades. As always, node operators will be notified in advance (via our Discord channel) if this upgrade is accompanied by a purge. You can also purge your node if your individual data directory becomes corrupted.

To do so, first stop the docker container or systemd service:

sudo docker stop `CONTAINER_ID`
# or
sudo systemctl stop moonbeam

Next, remove the db folder, where the parachain information is stored:

sudo rm -rf /var/lib/alphanet-data/chains/moonbase_alpha/db

Lastly, install the newest version by repeating the steps described before, making sure you are using the latest tag available. If so, you can start a new node with a fresh data directory.

Telemetry¶

To enable your Moonbase Alpha node's telemetry server, you can follow this tutorial.

Running telemetry on a full node is not necessary. However, it is a requirement to do so for collators.

Also, you can see current Moonbase Alpha telemetry information visiting this link.

Logs and Troubleshooting¶

You will see logs from both the relay chain as well as the parachain. The relay chain will be prefixed by [Relaychain], while the parachain has no prefix.

Note

There is currently a bug in cumulus regarding the naming issue.

P2P Ports Not Open¶

If you don't see an Imported message (without the [Relaychain] tag), you need to check the P2P port configuration. P2P port must be open to incoming traffic.

In Sync¶

Both chains must be in sync at all times, and you should see either Imported or Idle messages and have connected peers.

Genesis Mismatching¶

The Moonbase Alpha TestNet is often upgraded. Consequently, you may see the following message:

DATE [Relaychain] Bootnode with peer id `ID` is on a different 
chain (our genesis: GENESIS_ID theirs: OTHER_GENESIS_ID)

This typically means that you are running an older version and will need to upgrade.

We announce the upgrades (and corresponding chain purge) via our Discord channel at least 24 hours in advance.

We Want to Hear From You¶

If you have any feedback regarding running a full node or any other Moonbeam-related topic, feel free to reach out through our official development Discord server.