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-8
is bundle-testnet-8
. You can obtain the Unionvisor bundle for union-testnet-8
from our GitHub Container Registry.
Alternatively, you can run the following command:
docker pull ghcr.io/unionlabs/bundle-testnet-8:$UNIONVISOR_VERSION
Where UNIONVISOR_VERSION
is v0.24.0
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.
docker run \
--volume ~/.unionvisor:/.unionvisor \
--volume /tmp:/tmp \
-it ghcr.io/unionlabs/bundle-testnet-8:$UNIONVISOR_VERSION \
init --moniker $MONIKER \
--network union-testnet-8 \
--seeds "c2bf0d5b2ad3a1df0f4e9cc32debffa239c0af90@testnet.seed.poisonphang.com:26656"
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.24.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.
Using Snapshots or State Sync
For networks that have been producing blocks for more than a few weeks, syncing from genesis is often not recommended. Most validators and node operators prefer to use node snapshots or state sync to jump start their nodes.
To use state sync or node snapshots with Unionvisor, you will need to use the set-uniond-version
sub-command of Unionvisor. You should set Unionvisor to use the version of uniond
that was used to generate the node snapshot or state sync snapshot.
You can use the set-uniond-version
command as follows:
docker run \
--volume ~/.unionvisor:/.unionvisor \
--volume /tmp:/tmp \
-it ghcr.io/unionlabs/bundle-testnet-8:$UNIONVISOR_VERSION \
set-uniond-version $UNIOND_VERSION
Where UNIOND_VERSION
is the version of uniond
used when the snapshot was generated
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 ghcr.io/unionlabs/bundle-testnet-8:$UNIONVISOR_VERSION --log-level off call --'
Where UNIONVISOR_VERSION
is v0.24.0
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:
services:
node:
image: ghcr.io/unionlabs/bundle-testnet-8:$UNIONVISOR_VERSION
volumes:
- ~/.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