Skip to content

Running Unionvisor

Unionvisor is a utility for managing uniond deployments. It manages running, upgrading, and interacting with the node.

Obtaining Unionvisor

We release container images of Unionvisor called bundles. Each bundle contains everything required for running Unionvisor and joining a particular network. The Unionvisor bundle for union-testnet-6 is bundle-testnet-6. You can obtain the Unionvisor bundle for union-testnet-6 from our GitHub Container Registry.

Alternatively, you can run the following command:



Running Unionvisor

Before running this image, we need to create a folder to host the chain configuration and state.

You can create this wherever you would like, but we’ll be doing so in our current user’s home directory.

To create a directory for unionvisor in your user home directory, run:

mkdir ~/.unionvisor

Initializing the Chain Config & State Folder

Now, using the unionvisor image and the folder we just created, we can initialize the contents of this folder.

To do this, we’ll be using Docker volumes.

Terminal window
docker run \
--volume ~/.unionvisor:/.unionvisor \
--volume /tmp:/tmp \
init --moniker $MONIKER \
--network union-testnet-6 \
--seeds ""

Where MONIKER is the preferred moniker you’d like to use on this node.

After the above command is done running, you should have a .unionvisor folder with the following contents:

  • Directoryhome
    • Directoryconfig
      • app.toml
      • client.toml
      • config.toml
      • genesis.json
      • node_key.json
      • priv_validator_key.json
    • Directorydata
      • priv_validator_state.json
  • Directoryversions
    • v0.19.0- uniond

Migrating an Existing Node (Optional)

If you have an existing node, either from running the uniond image or raw binary - you can migrate it to Unionvisor starting here.

To migrate, you only need to copy over your uniond state into the ~/.unionvisor/home directory - then start Unionvisor normally.

If you have a uniond state saved to ~/.union, you can run the following command.

sudo cp -r ~/.union/* ~/.unionvisor/home

Then continue to follow the guide normally.

Issuing Sub-Commands to uniond via Unionvisor

To run uniond sub-commands, it will be useful to alias the Docker command in your shell .*rc file.

For example, in zsh, you can add the following alias to your .zshrc:

alias uniond='docker run -v ~/.unionvisor:/.unionvisor -v /tmp:/tmp --network host -it$UNIONVISOR_VERSION --log-level off call --'


This will enable you to issue uniond sub-commands with such as uniond keys add with ease.

Starting the Node

To run a node using Unionvisor, you’ll also need to expose ports to the container. We’ll use this as an opportunity to create a Docker Compose file four Unionvisor.

A minimal Docker Compose file for Unionvisor looks like this:

- ~/.unionvisor:/.unionvisor
- /tmp:/tmp
network_mode: "host"
restart: unless-stopped
command: run --poll-interval 1000

This will mount our chain configuration and settings folder while also exposing ports 26657, 1317, and 9093.

After creating a compose.yml file with the contents above, you’ll be able to start your Union node with docker compose.

Before starting your Union node for the first time, you should configure your node correctly.

For some configuration recommendations see our Node Configuration page.

To run your node in detached mode, run:

docker compose --file path/to/compose.yaml up --detach