Setting Up a Polkadot Node (the easy way)

Polkadot’s launch is approaching fast. Proof-of-Concept 3 went live earlier this year, powering the new “Alexander” testnet. Mainnet launch is scheduled for Q4 2019, bridging Substrate, Ethereum and other parachains.
Whether you’re a developer or prospective buidler, the first thing anyone interested in Polkadot should do is setup a node and join the network.
TL;DR
We’ll use Docker and Polkadot’s latest Docker pre-built image (0.3.14) to spin up and sync a node in under 5 minutes. If you’ve never used Docker or don’t know what an image is, don’t worry, this article will guide you through the whole process.
Although Parity has done a great job documenting the steps, building Polkadot won’t be easy unless you’re a Rust developer. The reality is that compiling the software can be alot easier.
Let’s get started!
Install Docker
Docker is a tool that helps you build, test and deploy applications by using containers. Containers are essentially virtual machines (with their own memory, processing power and storage). Containers also hold libraries, tools and other dependencies necessary to run your app.
You can install Docker for desktop here.
Initialize Docker
Once installed, you can open Docker from your applications folder. Docker will then start and run from your Desktop. This will create a new container where we can setup our Polkadot node.
For the purpose of this tutorial we will use the following directory, where folder
is your working destination for this project:
/my/local/folder
If you’re using a local Polkadot binary, you may want to use the following folders:
OS-X: ~/Library/Application Support/Polkadot/
Linux: ~/.local/share/Polkadot/


Polkadot’s Pre-built Docker Images
A Docker image is a “multi-layer” file used to execute code within a Docker container. In a nutshell, Polkadot’s pre-built image will setup an environment (Rust + support software) and run a script to spin up a node from the Polkadot source code file.
You can find all versions of Polkadot’s pre-built Docker images here:
We will use version :
0.3.14

Getting Familiar with Commands
Here’s a list of commands you can run from shell:
docker run
will invoke docker and ask it to run a container.--rm
will delete and clean up the container once we terminate it.-it
will show the processes within the container.-p
will open the ports for communicating with your Polkadot node.-v
will mount a volume and store all chain data in a given folder directory.-d
will run the Docker container in the background rather than outputting logs.chevdor/polkadot:0.3.14
is the name and version of the pre-built image we will use.polkadot
will launch a Polkadot node (but won’t open ports or mount a volume).polkadot --version
will output the version of Polkadot and a hash.--help
will output a list of flags, options and subcommands.--name “<name>"
will provide a name to your node. Otherwise, Polkadot will find one for you.--chain alex
is an important argument, specifies chain when running any other POC-3 version (eg. 0.3.xx). Not needed if running a pre 0.3 version.
Setting Up a Polkadot Node
Check Version of Polkadot
Let’s use Docker to check what version of Polkadot we have:
$ docker run --rm -it chevdor/polkadot:0.3.14 polkadot --version
If it’s the first time trying to run the code from a pre-built image, Docker will probably respond with Unable to find image
. This means Docker couldn’t find the image locally and will need to download it. Docker will then pull the image from chevdor/polkadot:0.3.14
and output a hash (“Digest”) and “Status” message.
Polkadot Node (Basic Version)
You can run a simple Polkadot node by running the following command:
$ docker run --rm -it chevdor/polkadot:0.3.14 polkadot
This command sets up your node but won’t sync with the rest of the network. Meaning, it’ll appear in Telemetry but won’t sync with other peers and broadcast blocks. Take that in mind, we’ll spin up a “full” node in a bit.
Help Command
Running the following command will output a list of flags, options and subcommands:
$ docker run --rm -it chevdor/polkadot:0.3.14 polkadot --help
Polkadot Node (Full Version)
Now, to properly run a node we must:
- Open the required ports (connects to peers)
- Mount a volume (stores chain data locally)
We can use the -p
flag to open ports 30333:30333 and 9933:9933, which can be used to communicate with our node (send transactions, state of block, etc).
We’ll mount a volume by using the -v
flag. Let’s store all our chain data in /my/local/folder
. This saves all the data (blocks) that were previously synchronized in case the node crashes for whatever reason. This will also allow you to resume your container incase you decide to stop and start it again.
$ docker run --rm -it -p 30333:30333 -p 9933:9933 -v /my/local/folder/:/data chevdor/polkadot:0.3.14 polkadot --chain alex --name "Alzheimer"
Connect to a specific chain by adding --chain
, use --chain alex
if you’re using any other version of the Proof-of-Concept 3 software (eg. 0.3.xx). You don’t need to do this if you’re running a POC 2 node (Krumme Lanke, 0.2.xx).
Add a custom node name by adding the --name "YourName"
at the end.

Run the Node in the Background
You can also run a Polkadot node as a daemon, and have Docker running in the background. This is done by adding -d
:
docker run -d -p 30333:30333 -p 9933:9933 -v /my/local/folder/:/data chevdor/polkadot:0.3.14 polkadot --chain alex --name "Alzheimer"
C’est Fini!
Congratulations, if all steps were executed correctly, you should be able to view your node on telemetry.polkadot.io/≥/

Setting up your Polkadot node is just the start. The next steps would be to download the Polkadot UI, create an account (on POC-2 or POC-3) and request sample DOTs from the Riot chat. More to come soon!
References and Further Reading
- Credit goes to Wilfried Kopp for providing the Docker images: hub.docker.com/r/chevdor/polkadot/tags/ , I’ve merely created a wrapper for others to get started.
- Parity Docker instructions: github.com/paritytech/polkadot/blob/master/doc/docker.adoc
- Polkadot repo on Github: github.com/paritytech/polkadot
- Polkadot Network: polkadot.network/
- Preparing for Substrate/Polkadot Integration: medium.com/polkadot-network/preparing-for-polkadots-launch-with-substrate-cb97819ed815
- Telemetry: telemetry.polkadot.io/#/Alexander
- Polkadot UI App: polkadot.js.org/apps