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".
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)"
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:
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).
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".
[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
[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
We can also check the logs by executing:
journalctl -f -u moonbeam.service
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
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.