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.

Caution

It’s important that you will be able to edit this contents of this folder.

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.

Note

Note the usage of the flags and arguments we pass to docker run run here:

• --user $(id -u):(id -g) ensures that the container is being created and ran with the current user and their permissions
• --volume ~/.union:/.union mounts the folder we created to the /.union folder of the container
• -it ensures we are running the container interactively

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.

Caution

Before starting your Union node for the first time, you should configure your node correctly and obtain the genesis file.

For some configuration recommendations see our Node Configuration page.

You can download the genesis here:

genesis.json

To run your node in detached mode, run:

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