Getting started with a single server node

Setup & manage your node

Hardware requirements

The recommended minimum specifications are 2.2GHz CPU, and 2GB RAM with at least 20 GB of storage space.

Installation instructions

Read Me First

Please keep in mind that we will give our best to support you while setting up and testing the nodes. Some features are subject to change and we are aware that some defects may show up on different installations and usage scenarios.

If you need help installing OT Node or troubleshooting your installation, you can either:

  • engage in our Discord community and post your question,
  • contact us directly via email at

Nodes can be installed in two ways:

  • via docker, which is recommended way, also explained on our website
  • manually

NOTE: For best performance on running a node we recommend usage of services like Digital Ocean.


System requirements

  • minimum of 2Gb of RAM memory

  • at least 2 GB RAM / 2.2 GHz CPU

  • at least 20 GB storage space

  • Ethereum and/or xDai wallet (You can see wallet setup instructions here Identity Configuration)

  • for a testnet node:

    • For Ethereum: at least 3000 test TRAC tokens and at least 0.05 test Ether
    • For xDai: at least 3000 test xTRAC tokens and at least 0.01 xDai
  • for a mainnet node:

    • For Ethereum: at least 3000 TRAC tokens and at least 0.05 Ether
    • For xDai: at least 3000 xTRAC tokens and at least 0.01 xDai

Installation via Docker


Public IP or open communication

A public IP address, domain name, or open network communication with the Internet is required. If behind NAT, please manually setup port forwarding to all the node’s ports.

Docker installed

The host machine needs to have Docker installed to be able to run the Docker commands specified below. You can find instructions on how to install Docker here:

For Mac

For Windows

For Ubuntu

It is strongly suggested to use the latest official version.

Open Ports

By default Docker container will use 8900, 5278 and 3000 ports. These can be mapped differently in Docker container initialization command. Make sure they’re not blocked by your firewall and that they are open to the public.

Please note: port 8900 is used for REST API access which is not available until OT node is fully started. This can be concluded after the following log message is displayed in the running node.

info - OT Node started


Before running a node make sure you configure it properly first. You can proceed to the Node Configuration page.

Run a node on the MAINNET

Let’s just point Docker to the right image and configuration file with the following command:

sudo docker run -i --log-driver json-file --log-opt max-size=1g --name=otnode -p 8900:8900 -p 5278:5278 -p 3000:3000 -v ~/.origintrail_noderc:/ot-node/.origintrail_noderc origintrail/ot-node:release_mainnet

NOTE: Please make sure that your .origintrail_noderc file is ready before running the following commands. In this example, the configuration file .origintrail_noderc is placed into the home folder of the current user (ie. /home/ubuntu). You should point to the path where you created .origintrail_noderc on your file system.

Run a node on the TESTNET

Let’s just point Docker to the right image and configuration file with the following command:

sudo docker run -i --log-driver json-file --log-opt max-size=1g --name=otnode -p 8900:8900 -p 5278:5278 -p 3000:3000 -v ~/.origintrail_noderc:/ot-node/.origintrail_noderc origintrail/ot-node:release_testnet

NOTE: Please make sure that your .origintrail_noderc file is ready before running the following commands. In this example, the configuration file .origintrail_noderc is placed into the home folder of the current user (ie. /home/ubuntu). You should point to the path where you created .origintrail_noderc on your file system.

Manual installation



If you don’t have Node.js installed head to and install version 9.x.x.

Note: Make sure you have the precisely above specified version of Node.js installed. Some features will not work well on versions less or greater then 9.x.x.

Before starting, make sure your server is up-to-date. You can do this with the following commands:

curl -sL\_9.x | sudo -E bash
sudo apt-get install -y nodejs

Database - ArangoDB

ArangoDB is a native multi-model, open-source database with flexible data models for documents, graphs, and key-values. We are using ArangoDB to store data. In order to run OT node with ArangoDB you need to have a local ArangoDB server installed and running.

Head to, select your operating system and download ArangoDB. You may also follow the instructions on how to install with a package manager, if available. Remember credentials (username and password) used to log in to Arango server, since later on you will need to set them in .origintrail_noderc .


Clone the repository

git clone -b release/mainnet

in the root folder of a project (ot-node), create .env file. For manually running a mainnet node, add following variable in .env file:


or for manually running a testnet node,


Before running a node make sure you configure it properly first. You can proceed to node Node Configuration page.

and then run npm from root project folder

cd ot-node
npm install
npm run setup

Starting The Node

OT node consists of two servers RPC and Kademlia node. Run both servers in a single command.

npm start

You can see instructions regarding the data import on the following Import data

Important Notes

Before running your node for the first time you need to execute npm run setup to apply the initial configuration.

If you want to reset all settings you can use npm run setup:hard. If you want to clear all the cache and recreate the database and not delete your identity just run npm run setup.

In order to make the initial import, your node must whitelist the IP or host of the machine that is requesting the import in configuration i.e

    "network": {
        "remoteWhitelist": [ "", ""]

By default only localhost is whitelisted.

For more information see Node Configuration.

Useful commands

Check node status

To check if your node is running in Terminal, run the following command:

docker ps -a

This command will indicate if your node is running.

Starting OT Node

This command will start your node as a background process.

docker start otnode

This command will start your node in interactive mode and you will see the node’s process written in the terminal, but this command will not run your node as a background process, which means your node will stop if you close your Terminal/Console.

docker start -i otnode

Stopping OT Node

You can stop your node in the following two ways:

If you started your node with the docker start otnode command and you wish to stop it from running, use the following command in your terminal:

docker stop otnode

If you started your node by using the docker start -i otnode command, you can stop it either by closing the Terminal or simply by pressing the ctrl + c.



There’s a minimum set of config parameters that need to be provided in order to run a node, without which the node will refuse to start.

Basic configuration

To properly configure the node you will need to create a config file in JSON format and provide some basic parameters for node operation. This file will be loaded by ot-node upon startup. Let’s create the file .origintrail_noderc in OT node root directory and store all the information about what kind of configuration we want to set up. The bare minimum of settings that need to be provided are two valid blockchain wallet addresses (currently xDai and Ethereum are supported):

  • The address and private key of the operational wallet (OW), which maps to node_wallet (OW public address) and node_private_key (OW private key). The operational wallet will be used by your node to execute basic node functionalities like applying for data holding offers and confirming completed offers.
  • The public address of the management wallet in the management_wallet parameter. The management wallet will be used to indicate which wallet has the rights to withdraw funds from your profile. Make sure that you have access to this wallet and that it is secure

You have to have at least one blockchain implementation specified for your node to function, but you’re free to use any and all of the supported blockchain implementations. Please do not to change the blockchain_title and network_id parameters, as they are used to properly connect your configuration with your node.

You also need to provide a public web address or domain name of your node in the hostname field.

We create the .origintrail_noderc file with following content:

    "network": {
        "hostname": "your external IP or domain name here",
        "remoteWhitelist": [ "IP or host of the machine that is requesting the import", ""]
    "blockchain": {
        "implementations": [
                "blockchain_title": "Ethereum",
                "network_id": "ethr:mainnet",
                "rpc_server_url": "url to your RPC server i.e. Infura or own Geth server",
                "node_wallet": "your ethereum wallet address here",
                "node_private_key": "your ethereum wallet's private key here",
                "management_wallet": "your ethereum management wallet public key here"
                "blockchain_title": "xDai",
                "network_id": "xdai:mainnet",
                "rpc_server_url": "url to your RPC server i.e. Infura or own Geth",
                "node_wallet": "your xDai wallet address here",
                "node_private_key": "your xDai wallet's private key here",
                "management_wallet": "your xDai management wallet public key here"

node_wallet and node_private_key - the operational xDai/Ethereum wallet address and its private key.

management_wallet - the management wallet for your node (note: the Management wallet private key is NOT stored on the node)

hostname - the public network address or hostname that will be used in P2P communication with other nodes for node’s self identification.

remoteWhitelist - list of IPs or hosts of the machines (“”) that are allowed to communicate with REST API.

rpc_server_url - an URL to RPC host server, usually Infura or self hosted Geth server. For more see RPC server host

Configuration file

In general OT node uses [RC]( nodejs package to load configuration and everything mentioned there applies to the OT node.

Application name that will be used in detecting the config files is origintrail_node. Translated from RC package page a configuration file lookup will be like this (from bottom towards top):

command line arguments, parsed by minimist (e.g. –foo baz, also nested: –

environment variables prefixed with origintrail_node_

or use “__” to indicate nested properties (e.g. origintrail_node_foo__bar__baz =>

if you passed an option –config file then from that file

a local .origintrail_noderc or the first found looking in ./ ../ ../../ ../../../ etc.

  • $HOME/.origintrail_noderc
  • $HOME/.origintrail_node/config
  • $HOME/.config/origintrail_node
  • $HOME/.config/origintrail_node/config
  • /etc/origintrail_noderc
  • /etc/origintrail_node/config

the defaults object you passed in.

All configuration sources that were found will be flattened into one object, so that sources earlier in this list override later ones.

NOTE: To see all configuration parameters and their default values you can check this link:

Setting up an Ethereum RPC

For an OT node to use the Ethereum blockchain implementation it must communicate with the Ethereum blockchain. Such communication is achieved using the Ethereum JSON RPC protocol and a RPC compatible server.

RPC server configuration

The RPC server URL must be provided in the OT node’s configuration file and it should be placed in the Ethereum blockchain section as rpc_server_url. For example:

    "blockchain": {
        "implementations": [
                "blockchain_title": "Ethereum",
                "network_id": "ethr:mainnet",
                "rpc_server_url": "https://my.rpc.server.url:9000/"

For more on how to set up the configuration file go to Node Configuration

Using Infura as RPC host

Using Infura gives a lot of advantages such as not needing to host your own server or configuring the Ethereum node client or even not scaling the whole infrastructure.

In order to use it create an account at . Once logged-in you can create a project for which you’ll have project ID, project secret and the endpoint. That endpoint is the RPC server URL needed for the node to run. Make sure you pick the right one for the target network. Select RINKEBY to get the URL that will be used in the Testnet or MAINNET for the OriginTrail’s mainnet.

Using own Ethereum node as RPC host

To use the Ethereum node as an RPC server make sure it is properly configured and RPC feature is enabled (–rpc parameter). For more details on how to install and configure Ethereum node see: .

Once the Ethereum node is up and running use its URL to point to the OT node to use it.

Setting up an xDai RPC

The RPC server for the xDai blockchain is publicly available, so you do not need to add it in your configuration as it is already included in the ot-node default configuration.

Setting up SSL on a node

Before you begin setting up an SSL connection for a node’s remote API, make sure you have prepared certificates and registered a domain. Once you have enabled a secure connection, it will be used for both API (default port 8900) and remote control (default port 3000). If you are using different ports than the defaults, make sure you map them correctly during container initialization.


Make sure your certificates are in PEM format and stored locally, as you will need to provide them to the node or Docker container running the node.


Let’s assume that your domain certificates (for example: are stored in /home/user/certs. The fullchain.pem and privkey.pem files should be in that dir.

Edit the node’s configuration file and make sure it has the following items in the JSON root:

"node_rpc_use_ssl": true,
"node_rpc_ssl_cert_path": "/ot-node/certs/fullchain.pem",
"node_rpc_ssl_key_path": "/ot-node/certs/privkey.pem",

With the above, we are telling the node to find a certificate at the following path: /ot-node/certs/. That is where we are going to leave them in the container.

Now, create the docker container and mount cert dir into the container. We can achieve this by adding additional parameters ‘-v /home/user/certs:/ot-node/certs/’ to the container creation command. For example, the initialization of the Docker container for the OT node for the mainnet could look like this:

sudo docker run -i --name=otnode -p 8900:8900 -p 5278:5278 -p 3000:3000 -v /home/user/certs:/ot-node/certs/ -v ~/.origintrail_noderc:/ot-node/.origintrail_noderc origintrail/ot-node:release_mainnet

After this, the running container will be able to find certificate files at the ‘/ot-node/certs/’ location.

How to update

OT Node has a built-in update functionality which will be triggered upon OT Node start.


In order to trigger the update, you must restart the OT Node by using the following command:

docker restart otnode

After a successful update OT Node will be rebooted automatically.

NOTE: By default node comes with the auto update feature turned on (it can be turned off using configuration). If auto update is on, Node checks for the update every 6 hours and it will automatically download and install the newest version when it’s available. Without need for manual restart.

Manual installation

Make sure that you are in the root directory of OT Node. The following commands will update the OT Node.

git pull
docker stop otnode

Database migrations need to be triggered manually.

node_modules/.bin/sequelize --config=./config/sequelizeConfig.js db:migrate

Database seed needs to be triggered manually as well.

node_modules/.bin/sequelize --config=./config/sequelizeConfig.js db:seed

In order to apply the update, you must restart the OT Node by using the following command:

docker start otnode