Skip to content

Running the Client Binary

Currently, we are only officially supporting running the Union Testnet binary (uniond) as a Docker container.

It is possible to run the uniond binary outside of containers, however, we aren’t directly supplying bare-metal binaries at this time.

This guide assumes you have Docker correctly installed and configured on your system. We provide uniond images for Linux on both x86_64 (amd64) and aarch64 (arm64).

Getting the Docker Image

To get the uniond image, you can visit our container on the GitHub Container Registry, or run the following command:

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

Where UNIOND_VERSION is v0.24.0

Running uniond

Creating a Chain Config & State Folder

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 uniond in your user home directory, run:

mkdir ~/.union

Initializing the Chain Config & State Folder

Now, using the uniond 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 \
--user $(id -u):$(id -g) \
--volume ~/.union:/.union \
--volume /tmp:/tmp \
-it ghcr.io/unionlabs/uniond-release:$UNIOND_VERSION init $MONIKER \
--home /.union

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

After the uniond init command is done running, you should have a .union folder with the following contents:

  • Directoryconfig
    • app.toml
    • client.toml
    • config.toml
    • genesis.json
    • node_key.json
    • priv_validator_key.json
  • Directorydata
    • priv_validator_state.json

Issuing Sub-Commands to uniond

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 ~/.union:/.union -v /tmp:/tmp --network host -it ghcr.io/unionlabs/uniond-release:$UNIOND_VERSION --home /.union'

Where UNIOND_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 uniond, you’ll also need to expose ports to the container. We’ll use this as an opportunity to create a Docker Compose file four uniond.

A minimal Docker Compose file for uniond looks like this:

services:
node:
image: ghcr.io/unionlabs/uniond-release:${UNIOND_VERSION}
volumes:
- ~/.union:/.union
- /tmp:/tmp
network_mode: "host"
restart: unless-stopped
command: start --home /.union

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.

To run your node in detached mode, run:

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