Skip to content

Run a Node on Moonbeam Using Docker

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.

Installation Instructions

A Moonbeam node can be spun up quickly using Docker. For more information on installing Docker, please visit Get Docker on Docker's documentation. At the time of writing, the Docker version used was 19.03.6. When connecting to Moonriver on Kusama or Moonbeam on Polkadot, it will take a few days to completely sync the embedded relay chain. Make sure that your system meets the requirements.

Create a local directory to store the chain data:

mkdir /var/lib/moonbeam-data

mkdir /var/lib/moonriver-data

mkdir /var/lib/alphanet-data

Next, make sure you set the ownership and permissions accordingly for the local directory that stores the chain data. In this case, set the necessary permissions either for a specific or current user (replace INSERT_DOCKER_USER for the actual user that will run the docker command):

# chown to a specific user
chown INSERT_DOCKER_USER /var/lib/moonbeam-data

# chown to current user
sudo chown -R $(id -u):$(id -g) /var/lib/moonbeam-data

# chown to a specific user
chown INSERT_DOCKER_USER /var/lib/moonriver-data

# chown to current user
sudo chown -R $(id -u):$(id -g) /var/lib/moonriver-data

# chown to a specific user
chown INSERT_DOCKER_USER /var/lib/alphanet-data

# chown to current user
sudo chown -R $(id -u):$(id -g) /var/lib/alphanet-data

Now, execute the docker run command. 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 to 16000. The minimum value is 2000, but it is below the recommended specs

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

Linux snippets 
docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain moonbeam \
--name="INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache <50% RAM in MB> \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain moonriver \
--name="INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache <50% RAM in MB> \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain alphanet \
--name="INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache <50% RAM in MB> \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"
MacOS snippets 
docker run -p 9944:9944 -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain moonbeam \
--name="INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run -p 9944:9944 -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain moonriver \
--name="INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run -p 9944:9944 -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain alphanet \
--name="INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

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.

Collator

Linux snippets 
docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain moonbeam \
--name="INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
--db-cache <50% RAM in MB> \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain moonriver \
--name="INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
--db-cache <50% RAM in MB> \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain alphanet \
--name="INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
--db-cache <50% RAM in MB> \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"
MacOS snippets 
docker run -p 9944:9944 -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain moonbeam \
--name="INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run -p 9944:9944 -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain moonriver \
--name="INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

docker run -p 9944:9944 -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
purestake/moonbeam:v0.33.0 \
--base-path=/data \
--chain alphanet \
--name="INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
-- \
--name="INSERT_YOUR_NODE_NAME (Embedded Relay)"

Note

For an overview of the above flags, please refer to the Flags page of our documentation.

Once Docker pulls the necessary images, your full Moonbeam (or Moonriver) node will start, displaying lots of information, such as the chain specification, node name, role, genesis state, and more:

Full Node Starting

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.

docker run -p 30334:30334 -p 30333:30333 -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 (live network state) and a best block (local node synced state).

Full Node Starting

Note

It may take a few days to completely sync the embedded relay chain. Make sure that your system meets the requirements.

If you followed the installation instructions for Moonbase Alpha, once synced, you will have a node of the Moonbase Alpha TestNet running locally!

If you followed the installation instructions for Moonbeam/Moonriver, once synced, you will be connected to peers and see blocks being produced on the Moonbeam/Moonriver network! Note that in this case you need to also sync to the Polkadot/Kusama relay chain, which might take a few days.

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.

  1. Stop the docker container:

    sudo docker stop INSERT_CONTAINER_ID

  2. Get the latest version of Moonbeam from the Moonbeam GitHub Release page

  3. Use the latest version to spin up your node. To do so, replace the version in the Full Node or Collator command with the latest and run it

Once your node is running again, you should see logs in your terminal.

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 Docker container:

  sudo docker stop INSERT_CONTAINER_ID

If you did not use the -v flag to specify a local directory for storing your chain data when you spun up your node, then the data folder is related to the Docker container itself. Therefore, removing the Docker container will remove the chain data.

If you did spin up your node with the -v flag, you will need to purge the specified directory. For example, for the suggested data directly, you can run the following command to purge your parachain and relay chain data:

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

Last update: September 22, 2023
| Created: November 17, 2021