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/nodeto run a (non-configured) Universa node. You don’t even need the Universa codebase present for that!
docker run universa/uniclientto 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:
- universa/node – the primary image with the Universa software; includes the Universa node as well as the uniclient.
- universa/uniclient – the shortcut image for Uniclient launch.
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 running Linux: Centos, Debian, Fedora, Ubuntu, any other Linux variety. You may also to examine this article in Docker manuals.
- If you are running macOS: macOS Docker setup manual.
- If you are running Windows: Windows Docker setup manual.
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
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:
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
Assuming that you’ve cloned the Universa GitHub repository from
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
-dflag 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 donemessages).
docker-compose -p universa_4nodes -f docker/compose/docker-compose.yaml down– to bring down this network.
|Container||External host||External Ports||Internal IPv4||Internal IPv6||Internal Ports|
|node-1-local||localhost||2052, 2082, 2700||10.6.0.11||fdf0:e132:efcf:2fae::11||2052, 2082, 2700|
|node-2-local||localhost||2053, 2083, 2701||10.6.0.12||fdf0:e132:efcf:2fae::12||2052, 2082, 2700|
|node-3-local||localhost||2054, 2084, 2702||10.6.0.13||fdf0:e132:efcf:2fae::13||2052, 2082, 2700|
|node-4-local||localhost||2055, 2085, 2703||10.6.0.14||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
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
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