Run a node with Docker#

In this guide, you learn how to run a node on your Linux computer that participates in the Concordium network. This means that you receive blocks and transactions from other nodes, as well as propagate information about blocks and transactions to the nodes in the Concordium network. After following this guide, you will be able to

  • run a Concordium node

  • observe it on the network dashboard and

  • query the state of the Concordium blockchain directly from your machine.

You do not need an account to run a node.

Before you begin#

Before running a Concordium node you will need to

  1. Install and run Docker.

    • On Linux, allow Docker to be run as a non-root user.

  2. Download and extract the full suite for running a Mainnet node on Linux or full suite for running a Testnet node on Linux.

Running/upgrading a node#

To start running a client that will join Mainnet or Testnet follow these steps:

  1. Open the concordium-node executable from the unzipped archive.

    • When restarting a node consider using the --no-block-state-import option. This will download just the updates to the Concordium blockchain that occurred while the node was inactive and might speed up the boot process.

  2. Enter a name for your node. This name will be displayed in the public dashboard.

  3. If the tool has been started before you will be asked if you want to delete the local node database before starting. Pressing y will delete and subsequently recreate the information on the state of the Concordium blockchain that was saved on your computer. Note that deleting the local node database means it will take longer for your node to catch-up with the Concordium network.

The tool will now download the Concordium Client image and load it into Docker. The client will launch and start outputting logging information about the operation of the node.


To upgrade you have to restart the node. The tool automatically checks for the newest version.

Seeing your node on the dashboard#

After running concordium-node you can

Network dashboard#

It will take the client a while to catch up with the state of the Concordium blockchain. This involves, for example, downloading information about all the blocks in the chain.

Among other information, on the Network Dashboard you can get an idea of how long it will take your node to catch up with the chain. For that you can compare the node’s Length value (number of blocks your node received) with the Total Length value (number of blocks in the longest chain in the network) which is displayed at the top of the dashboard.

Enable inbound connections#

If you are running your node behind a firewall, or behind your home router, then you will probably only be able to connect to other nodes, but other nodes will not be able to initiate connections to your node. This is perfectly fine, and your node will fully participate in the Concordium network. It will be able to send transactions and, if so configured, to bake and finalize.

However you can also make your node an even better network participant by enabling inbound connections. By default, concordium-node listens on port 8888 for inbound connections on Mainnet and on port 8889 for inbound connections on Testnet. Depending on your network and platform configuration you will either need to forward an external port to 8888 or 8889 on your router, open it in your firewall, or both. The details of how this is done will depend on your configuration.

Configuring ports and tokens#

The node listens on four ports, which can be configured by supplying the appropriate command line arguments when starting the node. The ports used by the node are as follows:

  • 8888, the port for peer-to-peer networking, which can be set with --listen-node-port

  • 8082, the port used by middleware, which can be set with --listen-middleware-port

  • 8099, the port used by the node dashboard, which can be set with --listen-dashboard-port

  • 10000, the gRPC port for mainnet, which can be set with --listen-grpc-port

  • 10001, the gRPC port for testnet, which can be set with --listen-grpc-port

An additional mapping is the gRPC token, which defaults to rpcadmin, and can be set with --rpc-server-token.

When changing the mappings above the docker container must be stopped (Stop the node), reset, and started again. To reset the container either use concordium-node-reset-data or run docker rm concordium-client in a terminal.

It is strongly recommended that you configure your firewall to only allow public connections on port 8888 (the peer-to-peer networking port). Someone with access to the other ports might be able to take control of your node or accounts you have saved on the node.


Docker makes changes to the iptable on Linux, which means that it is not easy to block ports in practice. This is especially a problem when using UFW. Because the gRPC port is currently not considered secure, we strongly recommend changing the default gRPC token via the --rpc-server-token flag when running a node. This will provide reasonable security if the token is only ever used through a secure channel.

Run a baker node on Docker#

For information about how to configure a node to run as a baker, see Run a baker node on Docker.

Stop the node#

To stop the node, press CTRL+c, and wait for the node to do a clean shutdown.

If you accidentally close the window without explicitly shutting down the client, it will keep running in the background in Docker. In that case, use the concordium-node-stop binary in the same way you opened the concordium-node executable.

Retrieve node logs#

Logging information for your node can be retrieved using the concordium-node-retrieve-logs tool. This will save logs from the running image to a file. Additionally, if given permission, it will retrieve information about the programs currently running on the system.