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.

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

Checking Prerequisites¶

To get started, you'll need to:

• Install Docker. At the time of writing, the Docker version used was 24.0.6
• 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

Set up Storage for Chain Data¶

To set up the directory for storing chain data, you'll need to:

1. Create a local directory

   MoonbeamMoonriverMoonbase Alpha

   mkdir /var/lib/moonbeam-data
   

   mkdir /var/lib/moonriver-data
   

   mkdir /var/lib/alphanet-data
   

2. Set the ownership and permissions for the local directory that stores the chain data. You can set the permissions either for a specific or current user (replace INSERT_DOCKER_USER for the actual user that will run the docker command)

   MoonbeamMoonriverMoonbase Alpha

   # 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
   

Start-up Commands¶

To spin up your node, you'll need to execute the docker run command. If you're setting up a collator node, make sure to follow the code snippets for collators.

Note that in the following start-up command, 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

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¶

docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.0 \
--base-path /data \
--chain moonbeam \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.0 \
--base-path /data \
--chain moonriver \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.42.1 \
--base-path /data \
--chain alphanet \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

docker run -p 9944:9944 -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.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)" \
--sync fast

docker run -p 9944:9944 -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.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)" \
--sync fast

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

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.

docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.0 \
--base-path /data \
--chain moonbeam \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
--unsafe-rpc-external \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

docker run -p 9944:9944 -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.0 \
--base-path /data \
--chain moonbeam \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--unsafe-rpc-external \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

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.

docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.0 \
--base-path /data \
--chain moonbeam \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
# This is a comment
--db-cache INSERT_RAM_IN_MB \
--frontier-backend-type sql \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

docker run -p 9944:9944 -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.0 \
--base-path /data \
--chain moonbeam \
--name "INSERT_YOUR_NODE_NAME" \
--state-pruning archive \
--trie-cache-size 1073741824 \
--frontier-backend-type sql \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

Collator Node¶

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:

docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
 moonbeamfoundation/moonbeam:v0.41.0 key generate-node-key --base-path /var/lib/moonbeam-data --chain moonbeam 

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
 moonbeamfoundation/moonbeam:v0.41.0 key generate-node-key --base-path /var/lib/moonriver-data --chain moonriver 

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
 moonbeamfoundation/moonbeam:v0.42.1 key generate-node-key --base-path /var/lib/alphanet-data --chain alphanet && sudo chown -R moonbase_service  /var/lib/alphanet-data

Now you can run your Docker start up commands:

docker run --network="host" -v "/var/lib/moonbeam-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.0 \
--base-path /data \
--chain moonbeam \
--name "INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

docker run --network="host" -v "/var/lib/moonriver-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.41.0 \
--base-path /data \
--chain moonriver \
--name "INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

docker run --network="host" -v "/var/lib/alphanet-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moonbeamfoundation/moonbeam:v0.42.1 \
--base-path /data \
--chain alphanet \
--name "INSERT_YOUR_NODE_NAME" \
--collator \
--trie-cache-size 1073741824 \
--db-cache INSERT_RAM_IN_MB \
-- \
--name "INSERT_YOUR_NODE_NAME (Embedded Relay)" \
--sync fast

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

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

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

Syncing Your Node¶

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

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 followed the installation instructions for Moonbase Alpha, once synced, you will have a node of the Moonbase Alpha TestNet running locally! For Moonbeam or Moonriver, once synced, you will be connected to peers and see blocks being produced on the network!

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.

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