COSMOS OMNIBUS - Run Cosmos Nodes on Akash

This is a meta package of cosmos-sdk-based docker images and configuration meant to make deploying onto Akash easy and standardized across cosmos.

The goal is to have a simple way to launch any cosmos chain, with a variety of different bootstrapping options

1. "normal" boostrap - using fastsync.
2. Hand-made snapshots a la cosmos-snapshots
3. The new state-sync mechanism.

Configuration is achieved using environment variables, with shortcuts available for common setups. Every aspect of the node configuration can be achieved in this way.

Additional features are included to make running a node as simple as possible

1. Chain configuration can be sourced from a remote JSON file
2. Genesis file can be downloaded and unzipped in various ways
3. Private keys can be backed up and restored from any S3 compatible storage provider, such as Sia or Storj via Filebase.
4. Snapshots of a nodes data directory can be created at a certain time or day and uploaded to an S3 storage provider

Generic image (binary downloaded at runtime)

Omnibus has a generic base image which can download the required binary at runtime. This is useful for chain upgrades, testnets, or using a different version than Omnibus primarily supports.

This generic image provides the Omnibus scripts and configuration helpers, and nothing else. Set the BINARY_URL environment variable to a .zip, .tar or .tar.gz URL, and configure PROJECT, PROJECT_DIR and PROJECT_BIN. Alternatively provide a Chain Registry CHAIN_JSON to configure everything automatically (where data is available).

Image URL: ghcr.io/akash-network/cosmos-omnibus:v1.0.0-generic

services:
  node:
    image: ghcr.io/akash-network/cosmos-omnibus:v1.0.0-generic
    env:
      - CHAIN_JSON=https://raw.githubusercontent.com/akash-network/net/main/mainnet/meta.json
      #
      # alternatively configure manually
      #
      # - PROJECT=akash
      # - PROJECT_DIR=.akash
      # - PROJECT_BIN=akash
      # - BINARY_URL=https://github.com/akash-network/node/releases/download/v0.36.0/akash_linux_amd64.zip
      # - BINARY_ZIP_PATH=build/akash-v0.36.0 # only required if expected binary file isn't in the ZIP root

More information on the generic image can be found at /generic, and configuration is detailed in depth below.

Networks (pre-built images)

The available docker images can be found here. They are tagged with the form $COSMOS_OMNIBUS_VERSION-$PROJECT-$PROJECT_VERSION.

Project	Version	Image
agoric	agoric-upgrade-7-2	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-agoric-agoric-upgrade-7-2	Example
akash	v0.36.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-akash-v0.36.0	Example
archway	v7.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-archway-v7.0.0	Example
assetmantle	v1.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-assetmantle-v1.0.0	Example
axelar	v0.34.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-axelar-v0.34.0	Example
bandchain	v2.5.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-bandchain-v2.5.1	Example
bitcanna	v3.1.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-bitcanna-v3.1.1	Example
bitsong	v0.17.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-bitsong-v0.17.0	Example
bostrom	v0.3.2	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-bostrom-v0.3.2	Example
canto	v8.1.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-canto-v8.1.1	Example
cheqd	0.6.9	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-cheqd-0.6.9	Example
chihuahua	v8.0.2	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-chihuahua-v8.0.2	Example
comdex	v14.1.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-comdex-v14.1.0	Example
cosmoshub	v21.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-cosmoshub-v21.0.0	Example
crescent	v4.2.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-crescent-v4.2.0	Example
cronos	v1.3.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-cronos-v1.3.0	Example
cryptoorgchain	v4.2.9	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-cryptoorgchain-v4.2.9	Example
decentr	v1.6.4	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-decentr-v1.6.4	Example
desmos	v6.2.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-desmos-v6.2.0	Example
dydx	v7.0.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-dydx-v7.0.1	Example
dymension	v3.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-dymension-v3.1.0	Example
emoney	v1.2.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-emoney-v1.2.0	Example
empowerchain	v2.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-empowerchain-v2.0.0	Example
evmos	v20.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-evmos-v20.0.0	Example
fetchhub	v0.11.3	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-fetchhub-v0.11.3	Example
gitopia	v2.1.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-gitopia-v2.1.1	Example
gravitybridge	v1.11.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-gravitybridge-v1.11.1	Example
impacthub	v0.18.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-impacthub-v0.18.1	Example
injective	v1.13.2-1723753267	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-injective-v1.13.2-1723753267	Example
irisnet	v2.0.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-irisnet-v2.0.1	Example
jackal	v4.2.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-jackal-v4.2.1	Example
juno	v25.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-juno-v25.0.0	Example
kava	v0.25.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-kava-v0.25.0	Example
kichain	5.0.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-kichain-5.0.1	Example
konstellation	v0.5.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-konstellation-v0.5.0	Example
kujira	v2.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-kujira-v2.0.0	Example
kyve	v1.5.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-kyve-v1.5.0	Example
likecoin	v4.2.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-likecoin-v4.2.0	Example
lumnetwork	v1.6.3	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-lumnetwork-v1.6.3	Example
mars	v1.0.2	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-mars-v1.0.2	Example
migaloo	v3.0.2	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-migaloo-v3.0.2	Example
neutron	v5.0.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-neutron-v5.0.1	Example
noble	v5.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-noble-v5.0.0	Example
nois	v1.0.5	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-nois-v1.0.5	Example
omniflixhub	v5.0.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-omniflixhub-v5.0.1	Example
osmosis	v27.0.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-osmosis-v27.0.1	Example
panacea	v2.2.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-panacea-v2.2.0	Example
passage	v2.4.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-passage-v2.4.0	Example
persistence	v10.3.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-persistence-v10.3.0	Example
regen	v5.1.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-regen-v5.1.1	Example
rizon	v0.4.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-rizon-v0.4.1	Example
sei	v5.7.5	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-sei-v5.7.5	Example
sentinel	v0.11.5	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-sentinel-v0.11.5	Example
shentu	v2.11.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-shentu-v2.11.0	Example
sifchain	v1.4.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-sifchain-v1.4.0	Example
sommelier	v4.0.2	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-sommelier-v4.0.2	Example
source	v3.0.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-source-v3.0.1	Example
stargaze	v12.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-stargaze-v12.0.0	Example
starname	v0.11.5	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-starname-v0.11.5	Example
stride	v24.0.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-stride-v24.0.0	Example
teritori	v2.0.6	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-teritori-v2.0.6	Example
terra	v2.11.8	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-terra-v2.11.8	Example
umee	v6.3.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-umee-v6.3.0	Example
ununifi	v4.0.1	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-ununifi-v4.0.1	Example
xpla	v1.6.0	ghcr.io/akash-network/cosmos-omnibus:v1.0.0-xpla-v1.6.0	Example

Example configurations

There are example files within each project subdirectory which include a sensible default configuration for each chain. Optional configuration options are commented out so you can easily enable them, and the node can be configured further using the docs below.

Running on Akash

See the deploy.yml example file in each chain directory which details the minimum configuration required. Use the configuration options below to add functionality. Note the commented out persistent storage configuration if needed.

Running locally/any docker host

See the docker-compose.yml example file in each chain directory to run each node using docker-compose up.

Snapshots

Omnibus can import chain snapshots from almost any location. Some examples are Chain Layer's QuickSync service and Polkachu's Tendermint Snapshots.

Appropriate snapshot configuration is included in most example configurations in the Omnibus repository. Check the project directories for more information.

Examples

See the _examples directory for some common setups, including:

• Statesync
• Load Balanced RPC Nodes
• Validator and TMKMS
• Validator and Public Sentries
• Validator with Private Sentries
• Snapshot Backup

Configuration

Cosmos blockchains can be configured entirely using environment variables instead of the config files. Every chain has its own namespace, but the format of the configuration is the same.

For example to configure the seeds option in the p2p section of config.toml, for the Akash blockchain:

AKASH_P2P_SEEDS=id@node:26656

The namespace for each of the supported chains in the cosmos omnibus can be found in the README in each project directory. In all cases it is the binary name in uppercase (e.g. akash -> AKASH, gaiad -> GAIAD etc).

The omnibus images allow some specific variables and shortcuts to configure extra functionality, detailed below.

Chain configuration

Chain config can be sourced from a chain.json file as seen in the Cosmos Chain Registry. The Chain Registry will be used automatically for all pre-built images, or whenever the PROJECT environment variable matches a Chain Registry ID. Set CHAIN_JSON to an alternative URL if required, or 0 to disable this behaviour entirely.

Variable	Description	Default	Examples
CHAIN_JSON	URL to a chain.json file detailing the chain meta		https://github.com/cosmos/chain-registry/blob/master/akash/chain.json
CHAIN_ID	The cosmos chain ID		akashnet-2
GENESIS_URL	URL to the genesis file in .gz, .tar.gz, or .zip format. Can be set by CHAIN_JSON		https://raw.githubusercontent.com/akash-network/net/main/mainnet/genesis.json
DOWNLOAD_GENESIS	Force download of genesis file. If unset the node will only download if the genesis file is missing		1
VALIDATE_GENESIS	Set to 1 to enable validation of genesis file	0	1

P2P

Peer information can be provided manually, or obtained automatically from the following sources:

• CHAIN_JSON URL with peer information included.
• Polkachu's live seed and peers.
• Any ADDRBOOK_URL where the config/addrbook.json file is hosted.

See Cosmos docs for more information.

Variable	Description	Default	Examples
P2P_SEEDS	Seed nodes. Can be set by CHAIN_JSON		id@node:26656
P2P_PERSISTENT_PEERS	Persistent peers. Can be set by CHAIN_JSON		id@node:26656
ADDRBOOK_URL	URL to an addrbook.json file		https://quicksync.io/addrbook.terra.json

Private key backup/restore

On boot, the container can restore a private key from any S3 storage provider. If this is configured and the key doesn't exist in S3 yet, it will be uploaded from the node.

This allows for a persistent node ID and validator key on Akash's ephemeral storage.

Filebase is a great way to use S3 with decentralised hosting such as Sia.

The node_key.json and priv_validator_key.json are both backed up, and can be encrypted with a password.

Variable	Description	Default	Examples
S3_KEY	S3 access key
S3_SECRET	S3 secret key
S3_HOST	The S3 API host	https://s3.filebase.com	https://s3.us-east-1.amazonaws.com
STORJ_ACCESS_GRANT	DCS Storj Access Grant token (replaces S3_KEY, S3_SECRET, S3_HOST
KEY_PATH	Bucket and directory to backup/restore to		bucket/nodes/node_1
KEY_PASSWORD	An optional password to encrypt your private keys. Shouldn't be optional

Statesync

Some shortcuts for enabling statesync. Statesync requires 2x nodes with snapshots enabled.

Statesync nodes can also be sourced from Polkachu's Statesync service automatically.

See an example of a statesync deployment.

Variable	Description	Default	Examples
STATESYNC_SNAPSHOT_INTERVAL	Take a snapshot to provide statesync every X blocks		500
STATESYNC_ENABLE	Enabling statesyncing from a node. Default true if STATESYNC_RPC_SERVERS is set
STATESYNC_RPC_SERVERS	Comma separated list of RPC nodes with snapshots enabled		ip:26657,ip2:26657
STATESYNC_TRUSTED_NODE	A trusted node to obtain trust height and hash from. Defaults to the first STATESYNC_RPC_SERVERS if set		ip:26657
STATESYNC_TRUST_PERIOD	Trust period for the statesync snapshot	168h0m0s
STATESYNC_TRUST_HEIGHT	Obtained from STATESYNC_TRUSTED_NODE
STATESYNC_TRUST_HASH	Obtained from STATESYNC_TRUSTED_NODE

Snapshot restore

The node data directory can be restored from a .tar, .tar.gz or .lz4 file stored on a public URL. The file can be obtained from the following sources:

• Direct URL to the archive file
• Base URL file listing, where the archive matches a given pattern.
• snapshot.json generated by Omnibus Snapshot backup feature.
• ChainLayer's Quicksync snapshots described by a JSON file.
• Polkachu's snapshot service, fully automatically.

Note that snapshots will be restored in-process, without downloading the snapshot to disk first. This saves disk space but is slower to extract, and could be made configurable in the future.

Variable	Description	Default	Examples
DOWNLOAD_SNAPSHOT	Force bootstrapping from snapshot. If unset the node will only restore a snapshot if the data contents are missing		1
SNAPSHOT_URL	A URL to a .tar, .tar.gz or .lz4 file		http://135.181.60.250/akash/akashnet-2_2021-06-16.tar
SNAPSHOT_BASE_URL	A base URL to a directory containing backup files		http://135.181.60.250/akash
SNAPSHOT_JSON	A URL to a snapshot.json as detailed in Snapshot backup		https://cosmos-snapshots.s3.filebase.com/akash/pruned/snapshot.json
SNAPSHOT_FORMAT	The format of the snapshot file	tar.gz	tar/tar.zst
SNAPSHOT_PATTERN	The pattern of the file in the SNAPSHOT_BASE_URL	$CHAIN_ID.*$SNAPSHOT_FORMAT	foobar.*tar.gz
SNAPSHOT_DATA_PATH	The path to the data directory within the archive		snapshot/data
SNAPSHOT_WASM_PATH	The path to the wasm directory within the archive, if exists outside of data		snapshot/wasm
SNAPSHOT_PRUNING	Type of snapshot to download, e.g. archive, pruned, default.	pruned	archive
SNAPSHOT_QUICKSYNC	A URL to a Quicksync JSON file describing their snapshots. Also see SNAPSHOT_PRUNING		https://quicksync.io/terra.json

Snapshot backup

Omnibus includes a script to automatically snapshot a node and upload the resulting archive to any S3 compatible service like Filebase. At a specified time (or day), the script will shut down the tendermint server, create an archive of the data directory and upload it. Snapshots older than a specified time can also be deleted. Finally a JSON metadata file is created listing the current snapshots. The server is then restarted and monitored.

See an example of a snapshot node deployment.

Variable	Description	Default	Examples
S3_KEY	S3 access key
S3_SECRET	S3 secret key
S3_HOST	The S3 API host	https://s3.filebase.com	s3.us-east-1.amazonaws.com
STORJ_ACCESS_GRANT	DCS Storj Access Grant token (replaces S3_KEY, S3_SECRET, S3_HOST
STORJ_UPLINK_ARGS	DCS Storj Uplink arguments	-p 4 --progress=false	-p 4 --parallelism-chunk-size 256M --progress=false
SNAPSHOT_PATH	The S3 path to upload snapshots to, including the bucket		cosmos-snapshots/akash
SNAPSHOT_PREFIX	The prefix for the snapshot filename	$CHAIN_ID	snapshot
SNAPSHOT_TIME	The time the snapshot will run	00:00:00	09:00:00
SNAPSHOT_DAY	The numeric day of the week the snapshot will run (Monday = 1)	*	7
SNAPSHOT_DIR	The directory on disk to snapshot	$PROJECT_ROOT/data	/root/.akash
SNAPSHOT_CMD	The command to run the server	$START_CMD	akash start --someflag
SNAPSHOT_RETAIN	How long to retain snapshots for (0 to disable)	2 days	1 week
SNAPSHOT_METADATA	Whether to create a snapshot.json metadata file	1	0
SNAPSHOT_METADATA_URL	The URL snapshots will be served from (for snapshot.json)		https://cosmos-snapshots.s3.filebase.com/akash
SNAPSHOT_SAVE_FORMAT	Overrides value from SNAPSHOT_FORMAT.	tar.gz	tar (no compression)/tar.zst (use zstd)

When SNAPSHOT_SAVE_FORMAT is set to tar.zst, additional variables can be set:

• ZSTD_CLEVEL - Compression level, default 3
• ZSTD_NBTHREADS - No. of threads, default 1, 0 = detected no. of cpu cores

Binary download

The node binary can be downloaded at runtime when using the Generic image. All configuration can be sourced from CHAIN_JSON if the attributes are available, or configured manually. You will need to set PROJECT, PROJECT_BIN and PROJECT_DIR if these can't be sourced from CHAIN_JSON.

Variable	Description	Default	Examples
BINARY_URL	URL to the binary (or zip, tar, tar.gz)
BINARY_ZIP_PATH	Path to the binary in the archive. Can be left blank if correctly named in root
PROJECT	Name of the project, informs other variables
PROJECT_BIN	Binary name	$PROJECT	osmosisd
PROJECT_DIR	Name of project directory	.$PROJECT_BIN	.osmosisd

Polkachu Services

Polkachu validator provides various Cosmos chain services that can be automatically enabled using environment variables.

Variable	Description	Default	Examples
P2P_POLKACHU	Import Polkachu's seed node and live peers if available		1
P2P_SEEDS_POLKACHU	Import Polkachu's seed node if available		1
P2P_PEERS_POLKACHU	Import Polkachu's live peers if available		1
STATESYNC_POLKACHU	Import Polkachu's statesync addresses if available		1
ADDRBOOK_POLKACHU	Import Polkachu's addrbook if available		1
POLKACHU_CHAIN_ID	Polkachu API chain-id if it differs from Chain Registry naming convention.		cryptocom

Cosmovisor

Cosmovisor can be downloaded at runtime to automatically manage chain upgrades. You should be familiar with how Cosmovisor works before using this feature.

Variable	Description	Default	Examples
COSMOVISOR_ENABLED	Enable Cosmovisor binary download and support		1
COSMOVISOR_VERSION	Version of Cosmovisor to download	1.6.0
COSMOVISOR_URL	Alternative full URL to Cosmovisor binary tar.gz

Shortcuts

See Cosmos docs for more information

Variable	Description	Default	Examples
MONIKER	The node's moniker	My Omnibus Node	Akash Node
FASTSYNC_VERSION	The fastsync version		v0
MINIMUM_GAS_PRICES	Minimum gas prices		0.025uakt
PRUNING	How much of the chain to prune		nothing
DOUBLE_SIGN_CHECK_HEIGHT	Set the double_sign_check_height config		10
DEBUG	Set to 1 to output all environment variables on boot. Set to 2 to debug shell scripts.		1, 2

Contributing

Adding a new chain is easy, but there are a few steps you need to follow:

The chain should exist in the Chain Registry to provide a single source of truth for chain info.

Add a project directory using the same name as the Chain Registry directory.

Add a build.yml file using the template below. Adjust the variables as required, and run it using docker-compose -f build.yml up --build. Adjust until you have a working node. Check other chains for alternate configurations.

Only include the environment section if there is recommended configuration for your chain. This will be copied to the documentation in the next step.

services:
  node:
    build:
      context: ../
      args:
        PROJECT: cosmoshub # should match the directory/Chain Registry
        PROJECT_BIN: gaiad
        PROJECT_DIR: .gaia
        VERSION: v21.0.0
        REPOSITORY: https://github.com/cosmos/gaia
        GOLANG_VERSION: 1.22-bullseye
        DEBIAN_VERSION: bullseye
        POLKACHU_CHAIN_ID: cosmos # only include if different from Chain Registry name
    # environment:
    #   - FASTSYNC_VERSION=v0
    ports:
      - '26656:26656'
      - '26657:26657'
      - '1317:1317'
    volumes:
      - ./node-data:/root/.gaia

Run the documentation script to automatically create deploy.yml, docker-compose.yml and README.md documentation files:

./document.sh mychainname

Update the main README.md file to include your chain in the Networks section. Keep this alphabetical and ensure the versions referenced are correct.

Update the .github/workflows/publish.yml file to include your chain and version. Again keep this alphabetical and ensure the versions referenced are correct.

Submit a PR with your changes and it will be validated and merged if appropriate.