Set Up a Node¶
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¶
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¶
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
Warning
This setup is not recommended for validators. If you plan to run a validator, refer to the Running a Validator guide for proper instructions.
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 stable
rustup update
rustup update nightly
rustup target add wasm32-unknown-unknown --toolchain nightly
rustup component add rust-src --toolchain stable-aarch64-apple-darwin
You can verify your installation by running:
You should see output similar to the following:
rustup +nightly show</span
active toolchain ---------------- stable-aarch64-apple-darwin (default) rustc 1.82.0 (f6e511eec 2024-10-15) active toolchain ---------------- nightly-aarch64-apple-darwin (overridden by +toolchain on the command line) rustc 1.84.0-nightly (03ee48451 2024-11-18)
Then, run the following commands to clone and build the Polkadot binary:
git clone https://github.com/paritytech/polkadot-sdk polkadot-sdk
cd polkadot-sdk
cargo build --release
Depending 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:
Ensure 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/polkadot
Info
The nature of pre-built binaries means that they may not work on your particular architecture or Linux distribution. If you see an error like cannot execute binary file: Exec format error it likely means the binary is incompatible with your system. You will either need to compile the binary or use Docker.
Ensure that you properly configure the permissions to make the Polkadot release binary executable:
Linux (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 stable
rustup update
rustup update nightly
rustup target add wasm32-unknown-unknown --toolchain nightly
rustup target add wasm32-unknown-unknown --toolchain stable-x86_64-unknown-linux-gnu
rustup component add rust-src --toolchain stable-x86_64-unknown-linux-gnu
You can verify your installation by running:
You should see output similar to the following:
rustup +nightly show</span
active toolchain ---------------- stable-x86_64-unknown-linux-gnu (default) rustc 1.82.0 (f6e511eec 2024-10-15)
Once Rust is configured, run the following commands to clone and build Polkadot:
git clone https://github.com/paritytech/polkadot-sdk polkadot-sdk
cd polkadot-sdk
cargo build --release
Compiling 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:
Install the Polkadot snap package:
Before 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:
Then to start the node service, run:
You can review the logs to check on the status of the node:
And at any time, you can stop the node service:
You can optionally prevent the service from stopping when snap is updated with the following command:
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-external
If 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-external
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.
Note
Not sure which type of node to run? Explore an overview of the different node types.
The base commands for running a Polkadot node are as follows:
This uses the default pruning value of the last 256 blocks:
You can customize the pruning value, for example, to the last 1000 finalized blocks:
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:
Once you've fully configured your start-up command, you can execute it in your terminal and your node will start syncing.
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¶
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¶
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:
| Created: October 16, 2024