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. Upon 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 --entrypoint /deploy/uniclient universa/node to execute uniclient, similarly.
  • If you clone the Universa Github repository from UniversaBlockchain/universa, you can run the basic local network using docker-compose -p docker -f docker/compose/docker-compose.yaml up -d

Docker images

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 are available:

  • universa/node – the primary image with the Universa software; includes the Universa node as well as the uniclient.
  • universa/debian-jdk8 – auxiliary image with the basic Debian Linux system and Oracle JDK, preconfigured for further use and to be a base for other Docker images (universa/node image is based on it).

These images are rebuilt automatically from the latest Github code.


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 run the sample Universa network with 4 nodes, you may want to install the Docker Compose as well; see details here.

Docker image

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

Entrypoint and executables

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

Though, besides the node, the uniclient executable is also available inside the image; so you may expect the following executables available inside it:

  • /deploy/uninode – to run the node;
  • /deploy/uniclient – to run the uniclient.

If you want to run the uniclient, you may want to override the default entrypoint and execute it like this as docker run --entrypoint /deploy/uniclient universa/node with any uniclient arguments, like below:

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

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; and for this directory to be available from inside the Docker image, you may want to map the appropriate Docker volume to some of your local paths. Consult the docker-compose.yaml and the sample node configuration files for the details of configuration.

Besides that, in the docker-compose.yaml 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 /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:

  • 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 want during the launch.

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 network. You can find the configuration files in the /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:

  • docker-compose -p docker -f docker/compose/docker-compose.yaml up -d – to start up this preconfigured 4-node network.
  • docker-compose -p docker -f docker/compose/docker-compose.yaml down – to bring down this network.

Network schema

Container External Ports Internal IP Internal Ports
db 5432 5432
node-1-local 2052, 2082,2700 2052, 2082, 2700
node-2-local 2053, 2083,2701 2052, 2082, 2700
node-3-local 2054, 2084,2702 2052, 2082, 2700
node-4-local 2055, 2085,2703 2052, 2082, 2700

Accessing the network

Currently, the existing clients (like uniclient) do not support connecting to your local Universa network directly; if are interested in further examining the network low-level operations, you may want to dig into the uniclient sources and slightly modify it access your local Universa nodes instead of the default universa.io addresses. You don’t even need to recompile it locally on your computer: you can rebuild the image using the regular Docker means, with the command like docker build --tag universa/node:latest --compress -f docker/node/Dockerfile .!

You can double-check that the network is running, though, using the command like this:

curl http://localhost:2052/network

It will output a bunch of incomprehensible symbols (as the HTTP-based node communication protocol actually transfers the optimized binary contents), which should start from something like 3resultok though, meaning that it is the Universa node handling and replying to this request.