Getting Started

This guide is intended for validators running on bare-metal servers and explains how Union releases work. Check out the NixOS and the Kubernetes guide for more production-ready deployments.

Validators are the backbone of the network. Becoming one requires significant token bonding and delegations, and is not intended for non-power users.

Obtaining uniond

Note

Currently, directly downloading the uniond binary requires access to our private GitHub repository. We are not currently providing the general public access to our GitHub repositories.

If you don’t have access to our private GitHub repository, you can still run our node using the public Docker image.

You can obtain uniond from a recent release.

Caution

Double-check the version and architecture in the link before downloading.

x86_64-linux

curl --output uniond --location https://github.com/unionlabs/union/releases/download/$UNIOND_VERSION/uniond-release-x86_64-linux

Where UNIOND_VERSION is v0.22.0

aarch64-linux

curl --output uniond --location https://github.com/unionlabs/union/releases/download/$UNIOND_VERSION/uniond-release-aarch64-linux

Where UNIOND_VERSION is v0.22.0

Verify that the binary works on your server by running:

./uniond --help

For convenience, we can add the binary to the PATH, to make it callable from anywhere.

mv ./uniond /usr/bin/

Using Docker

We also provide containers in our package registry.

docker pull ghcr.io/unionlabs/uniond-release:$UNIOND_VERSION

Where UNIOND_VERSION is v0.22.0

When running the container, make sure to map a volume to the path passed in --home options to ensure data persistence. From here on the guide assumes the usage of a regular binary. The docker-compose section is more suited for docker users.

Caution

uniond is a stateful application and interacts with the file system. Make sure to use volumes.

Initialization

We’ll need to set up a few configuration files and obtain the genesis.json before we can run the node.

First, set some environment variables, which are used throughout initialization.

export CHAIN_ID=union-testnet-8
export MONIKER="Unionized Goblin"
export KEY_NAME=alice
export GENESIS_URL="https://union.build/genesis.json"

Then we’ll have uniond initialize our data and configuration directories. By default, /User/{USER}/.uniond is used.

uniond init $MONIKER --chain-id $CHAIN_ID

Seeds

Next, edit ~/.union/config/config.toml. We’ll set the seeds to ensure your node can connect to the peer-to-peer network.

For union-testnet-8 replace seeds = "" with:

seeds = "c2bf0d5b2ad3a1df0f4e9cc32debffa239c0af90@testnet.seed.poisonphang.com:26656"

Genesis Configuration

Download the genesis.json and copy it to your uniond home directory.

curl $GENESIS_URL | jq '.result.genesis' > ~/.union/config/genesis.json

Registration

To join as a validator, you need to submit a registration transaction. You can do this from the command line on your validator node.

First, add a wallet that holds Union tokens.

uniond keys add $KEY_NAME --recover

Caution

For production usage, we recommend not storing the wallet on a server.

To submit the registration transaction and become a validator, you must submit a create-validator transaction:

uniond tx staking create-validator \
  --amount 1000000muno \
  --pubkey $(uniond tendermint show-validator) \
  --moniker $MONIKER \
  --chain-id $CHAIN_ID \
  --from $KEY_NAME \
  --commission-max-change-rate "0.1" \
  --commission-max-rate "0.20" \
  --commission-rate "0.1" \
  --min-self-delegation "1"

Note

If your own node isn’t set up to accept RPC request, you can send them to another node via the --node option.

Systemd Service

We recommend running uniond as a systemd service. Create a file in /etc/systemd/system called uniond.service. Make sure to replace $USER with your username.

[Unit]
Description=uniond
[Service]
Type=simple
Restart=always
RestartSec=1
User=$USER
ExecStart=/usr/bin/uniond start

[Install]
WantedBy=multi-user.target

You should be able to view the node logs by executing

sudo journalctl -f --user uniond

It’s then recommended to back up these files from ~/.union/config in a secure location:

• priv_validator_key.json
• node_key.json