Universa Docker images

To simplify running, debugging and learning the Universa network, the Docker images are provided which are capable of running the Universa core software with minimum OS configuration. Besides these Docker images, a sample network configuration is provided, demonstrating the basic 4-node network of Universa nodes.


  • docker run universa/node to run a (non-configured) Universa node. You don’t even need the Universa codebase present for that!
  • docker run universa/uniclient to run a (non-configured) Uniclient. Again, you don’t even need the Universa codebase!
  • If you clone the Universa GitHub repository from  UniversaBlockchain/universa, you can run the basic local network using docker-compose -p universa_4nodes -f docker/compose/docker-compose.yaml up -d


The Universa Docker images are provided in the official Docker Hub repository. The whole Universa project area can be seen at hub.docker.com/r/universa. The following Docker images may be of interest to you:

These images are rebuilt automatically from the latest GitHub code.

Note: there are also U8-related Docker images there; see the appropriate article for more details: U8 Docker images.


To use Docker images, you need to install the Docker software itself. See the installation details at the official Docker site; below are some download shortcuts for your convenience.

If you are going to use Docker Compose, you may want to install it as well; see details here.


universa/node: node server

The primary Docker image for running Universa node is universa/node. Running the command like docker pull universa/node will deliver it to your computer.


The entrypoint of this Docker image is the node launcher, which you can run with any supported arguments, e.g.:

docker run universa/node --help

To execute the node successfully, you may want to run it with -c DIRECTORY argument, to pass the directory with the configuration files and subdirectories. This directory should be mounted to the Docker container using the regular Docker means; consult the docker-compose.yaml and the sample node configuration files for the details of configuration.

Besides that, in the provided docker-compose.yaml script (see “Sample network configuration” section below) you will also find the hints how the PostgreSQL database can be linked to the Node image using the regular Docker image linking feature. See the  UniversaBlockchain/universa/…/docker/compose path in the project directory for details (including the files init-node.sh and init-user-db.sh which help you to initialize the database and pre-create the private keys for the nodes).


The following ports are exposed by default:

  • 2052 – port for HTTP Client (client-to-node) connections;
  • 2082 – port for HTTP Server (node-to-node) communication;
  • 2700 – port for UTP Server (node-to-node) communication.

As usual with the Docker images, you may map these ports (to your local ports) and volumes (to your local directories/files) as you need, during the launch.

universa/uniclient: Uniclient CLI

Uniclient is a convenient CLI tool for advanced operations with Universa network. Before using, you may want to read Uniclient User Manual.


The entrypoint of this Docker image is the Uniclient launcher, which you can run with any supported arguments, e.g.:

docker run universa/uniclient --help

You will find more information in the Uniclient User Manual. Here are some more commands to make sure everything is working.

Testing the Universa Mainnet availability and status:

docker run universa/uniclient --network

Checking the status of Universa UTN root contract (should be UNDEFINED):

docker run universa/uniclient --probe 'NPo4dIkNdgYfGiNrdExoX003+lFT/d45OA6GifmcRoTzxSRSm5c5jDHBSTaAS+QleuN7ttX1rTvSQbHIIqkcK/zWjx/fCpP9ziwsgXbyyCtUhLqP9G4YZ+zEY/yL/GVE'


Normally, Uniclient stores various data in ~/.universa directory inside your home dir. When running as a Docker container, please note it will virtualize its data inside the Docker volume; if you want to use the same directory as if you were running Uniclient normally, you may want to use the following option when running the container:

--mount type=bind,source="${HOME}/.universa",target=/root/.universa

Sample network configuration

Besides the Docker image for the Universa node, a sample (Docker Compose format) configuration is provided to launch 4 Universa nodes in a small local interconnected and breathing network. You can find the configuration files in the  UniversaBlockchain/universa/…/docker/compose path of the project directory.

Assuming that you’ve cloned the Universa GitHub repository from  UniversaBlockchain/universa, you may execute the following commands to use the network:

  • docker-compose -p universa_4nodes -f docker/compose/docker-compose.yaml up -d – to start up this preconfigured 4-node network (with the project name universa_4nodes). Running it without -d flag will let you see the logs of the bootstrap process (you may ignore some first-launch errors like “ERROR: relation "vars" does not exist at character 20” as long as it ends up with all initialization is done messages).
  • docker-compose -p universa_4nodes -f docker/compose/docker-compose.yaml down – to bring down this network.

Network schema

Container External host External Ports Internal IPv4 Internal IPv6 Internal Ports
db localhost 5432 fdf0:e132:efcf:2fae::10 5432
node-1-local localhost 2052, 2082, 2700 fdf0:e132:efcf:2fae::11 2052, 2082, 2700
node-2-local localhost 2053, 2083, 2701 fdf0:e132:efcf:2fae::12 2052, 2082, 2700
node-3-local localhost 2054, 2084, 2702 fdf0:e132:efcf:2fae::13 2052, 2082, 2700
node-4-local localhost 2055, 2085, 2703 fdf0:e132:efcf:2fae::14 2052, 2082, 2700

The network schema may look unusual comparing to the real Mainnet. The network communication between the nodes is happening over the IPv6 ports, while the topology announced by the nodes contains the “localhost” host. This makes it possible for the network nodes to communicate well within the Docker-established network (called universa_4nodes_net_4nodes by default, where universa_4nodes is the project-based prefix and net_4nodes is the network name; on the other hand, the localhost names announced let you connect to the exposed ports from your Docker host OS directly (e.g. using Uniclient).

Note though, due to this, you won’t be able to connect to this topology from inside the Docker network. docker run universa/uniclient won’t work! All the nodes share the same localhost announced location, shared by your Docker host OS; but inside the Docker network, each node will have its own independent “localhost”.

But on the other hand, the network will be fully reachable from your host OS, no matter it is communicating through inner (intra-Docker) channels only (thanks to our core network guru  Roman Uskov for the idea of this network architecture!)

Accessing the network

As mentioned above, to access the network, you need an Uniclient, or other client software installed at your host (using universa/uniclient Docker image, you won’t be able to access this network).

Normally, every client software needs a “topology” file containing the details about your network. The sample network is preconfigured with fixed private keys and IP addresses; so the topology file is also pre-built and available in the source code repository at  UniversaBlockchain/universa/…/docker/compose/universa.local.json.

This is how you can check the network availability using Uniclient (assuming Uniclient is properly installed, and you are running it from the directory containing the codebase):

uniclient --topology docker/compose/universa.local.json --network --no-cache

You will receive the reply like this (the network version may vary):

Network version: 3.13.3
Universa network is active, 4 node(s) are reachable