Set Up a Node
Introduction
Section titled “Introduction”Running a node on Polkadot provides direct interaction with the network, enhanced privacy, and full control over RPC requests, transactions, and data queries. As the backbone of the network, nodes ensure decentralized data propagation, transaction validation, and seamless communication across the ecosystem.
Polkadot supports multiple node types, including pruned, archive, and light nodes, each suited to specific use cases. During setup, you can use configuration flags to choose the node type you wish to run.
This guide walks you through configuring, securing, and maintaining a node on Polkadot or any Polkadot SDK-based chain. It covers instructions for the different node types and how to safely expose your node's RPC server for external access. Whether you're building a local development environment, powering dApps, or supporting network decentralization, this guide provides all the essentials.
Set Up a Node
Section titled “Set Up a Node”Now that you're familiar with the different types of nodes, this section will walk you through configuring, securing, and maintaining a node on Polkadot or any Polkadot SDK-based chain.
Prerequisites
Section titled “Prerequisites”Before getting started, ensure the following prerequisites are met:
- Ensure Rust is installed on your operating system.
- Install the necessary dependencies for the Polkadot SDK.
Install and Build the Polkadot Binary
Section titled “Install and Build the Polkadot Binary”This section will walk you through installing and building the Polkadot binary for different operating systems and methods.
macOS
To get started, update and configure the Rust toolchain by running the following commands:
source ~/.cargo/env
rustup default stablerustup update
rustup update nightlyrustup target add wasm32-unknown-unknown --toolchain nightlyrustup component add rust-src --toolchain stable-aarch64-apple-darwinYou can verify your installation by running:
rustup showrustup +nightly showYou should see output similar to the following:
Then, run the following commands to clone and build the Polkadot binary:
git clone https://github.com/paritytech/polkadot-sdk polkadot-sdkcd polkadot-sdkcargo build --releaseDepending upon the specs of your machine, compiling the binary may take an hour or more. After building the Polkadot node from source, the executable binary will be located in the ./target/release/polkadot directory.
Windows
To get started, make sure that you have WSL and Ubuntu installed on your Windows machine.
Once installed, you have a couple options for installing the Polkadot binary:
- If Rust is installed, then
cargocan be used similar to the macOS instructions. - Or, the instructions in the Linux section can be used.
Linux (pre-built binary)
To grab the latest release of the Polkadot binary, you can use wget:
wget https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-INSERT_VERSION/polkadotEnsure you note the executable binary's location, as you'll need to use it when running the start-up command. If you prefer, you can specify the output location of the executable binary with the -O flag, for example:
wget https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-INSERT_VERSION/polkadot \- O /var/lib/polkadot-data/polkadotEnsure that you properly configure the permissions to make the Polkadot release binary executable:
sudo chmod +x polkadotLinux (compile binary)
The most reliable (although perhaps not the fastest) way of launching a full node is to compile the binary yourself. Depending on your machine's specs, this may take an hour or more.
To get started, run the following commands to configure the Rust toolchain:
rustup default stablerustup updaterustup update nightlyrustup target add wasm32-unknown-unknown --toolchain nightlyrustup target add wasm32-unknown-unknown --toolchain stable-x86_64-unknown-linux-gnurustup component add rust-src --toolchain stable-x86_64-unknown-linux-gnuYou can verify your installation by running:
rustup showYou should see output similar to the following:
Once Rust is configured, run the following commands to clone and build Polkadot:
git clone https://github.com/paritytech/polkadot-sdk polkadot-sdkcd polkadot-sdkcargo build --releaseCompiling the binary may take an hour or more, depending on your machine's specs. After building the Polkadot node from the source, the executable binary will be located in the ./target/release/polkadot directory.
Linux (snap package)
Polkadot can be installed as a snap package. If you don't already have Snap installed, take the following steps to install it:
sudo apt updatesudo apt install snapdInstall the Polkadot snap package:
sudo snap install polkadotBefore continuing on with the following instructions, check out the Configure and Run Your Node section to learn more about the configuration options.
To configure your Polkadot node with your desired options, you'll run a command similar to the following:
sudo snap set polkadot service-args="--name=MyName --chain=polkadot"Then to start the node service, run:
sudo snap start polkadotYou can review the logs to check on the status of the node:
snap logs polkadot -fAnd at any time, you can stop the node service:
sudo snap stop polkadotYou can optionally prevent the service from stopping when snap is updated with the following command:
sudo snap set polkadot endure=trueUse Docker
Section titled “Use Docker”As an additional option, you can use Docker to run your node in a container. Doing this is more advanced, so it's best left up to those already familiar with Docker or who have completed the other set-up instructions in this guide. You can review the latest versions on DockerHub.
Be aware that when you run Polkadot in Docker, the process only listens on localhost by default. If you would like to connect to your node's services (RPC and Prometheus) you need to ensure that you run the node with the --rpc-external, and --prometheus-external commands.
docker run -p 9944:9944 -p 9615:9615 parity/polkadot:v1.16.2 --name "my-polkadot-node-calling-home" --rpc-external --prometheus-externalIf you're running Docker on an Apple Silicon machine (e.g. M4), you'll need to adapt the command slightly:
docker run --platform linux/amd64 -p 9944:9944 -p 9615:9615 parity/polkadot:v1.16.2 --name "kearsarge-calling-home" --rpc-external --prometheus-externalConfigure and Run Your Node
Section titled “Configure and Run Your Node”Now that you've installed and built the Polkadot binary, the next step is to configure the start-up command depending on the type of node that you want to run. You'll need to modify the start-up command accordingly based on the location of the binary. In some cases, it may be located within the ./target/release/ folder, so you'll need to replace polkadot with ./target/release/polkadot in the following commands.
Also, note that you can use the same binary for Polkadot as you would for Kusama or any other relay chain. You'll need to use the --chain flag to differentiate between chains.
The base commands for running a Polkadot node are as follows:
This uses the default pruning value of the last 256 blocks:
polkadot --chain polkadot \--name "INSERT_NODE_NAME"You can customize the pruning value, for example, to the last 1000 finalized blocks:
polkadot --chain polkadot \--name INSERT_YOUR_NODE_NAME \--state-pruning 1000 \--blocks-pruning archive \--rpc-cors all \--rpc-methods safeTo support the full state, use the archive option:
polkadot --chain polkadot \--name INSERT_YOUR_NODE_NAME \--state-pruning archive \--blocks-pruning archive \If you want to run an RPC node, please refer to the following RPC Configurations section.
To review a complete list of the available commands, flags, and options, you can use the --help flag:
polkadot --helpOnce you've fully configured your start-up command, you can execute it in your terminal and your node will start syncing.
RPC Configurations
Section titled “RPC Configurations”The node startup settings allow you to choose what to expose, how many connections to expose, and which systems should be granted access through the RPC server.
- You can limit the methods to use with
--rpc-methods; an easy way to set this to a safe mode is--rpc-methods safe. - You can set your maximum connections through
--rpc-max-connections, for example,--rpc-max-connections 200. - By default, localhost and Polkadot.js can access the RPC server. You can change this by setting
--rpc-cors. To allow access from everywhere, you can use--rpc-cors all.
For a list of important flags when running RPC nodes, refer to the Parity DevOps documentation: Important Flags for Running an RPC Node.
Sync Your Node
Section titled “Sync Your Node”The syncing process will take a while, depending on your capacity, processing power, disk speed, and RAM. The process may be completed on a $10 DigitalOcean droplet in about ~36 hours. While syncing, your node name should be visible in gray on Polkadot Telemetry, and once it is fully synced, your node name will appear in white on Polkadot Telemetry.
A healthy node syncing blocks will output logs like the following:
Congratulations, you're now syncing a Polkadot full node! Remember that the process is identical when using any other Polkadot SDK-based chain, although individual chains may have chain-specific flag requirements.
Connect to Your Node
Section titled “Connect to Your Node”Open Polkadot.js Apps and click the logo in the top left to switch the node. Activate the Development toggle and input your node's domain or IP address. The default WSS endpoint for a local node is:
ws://127.0.0.1:9944