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.


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:


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/

Docker is starting vs Docker is running.

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 :


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.
  • --rmwill 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.14is the name and version of the pre-built image we will use.
  • polkadotwill 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≥/

You can see our node “Alzheimer” at the top of the list. Via:

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