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

"normal" boostrap - using fastsync.
Hand-made snapshots a la cosmos-snapshots
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

Chain configuration can be sourced from a remote JSON file
Genesis file can be downloaded and unzipped in various ways
Private keys can be backed up and restored from any S3 compatible storage provider, such as Sia or Storj via Filebase.
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/ovrclk/cosmos-omnibus:v0.3.2-generic

services:
  node:
    image: ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-generic
    env:
      - MONIKER=my-moniker-1
      - CHAIN_JSON=https://raw.githubusercontent.com/ovrclk/net/master/edgenet/meta.json
      - BINARY_ZIP_PATH=akash_0.15.0-rc14_linux_amd64/akash

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-3.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-agoric-agoric-3.1`	Example
akash	`v0.16.3`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-akash-v0.16.3`	Example
assetmantle	`v0.3.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-assetmantle-v0.3.0`	Example
bandchain	`v2.3.3`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-bandchain-v2.3.3`	Example
bitcanna	`v1.4.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-bitcanna-v1.4.1`	Example
bitsong	`v0.11.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-bitsong-v0.11.0`	Example
bostrom	`v0.2.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-bostrom-v0.2.0`	Example
cerberus	`v1.0.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-cerberus-v1.0.1`	Example
cheqd	`v0.5.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-cheqd-v0.5.0`	Example
chihuahua	`v2.0.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-chihuahua-v2.0.1`	Example
chronicnetwork	`v1.1.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-chronic-v1.1.0`	Example
comdex	`v0.1.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-comdex-v0.1.1`	Example
cosmoshub	`v7.0.2`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-cosmoshub-v7.0.2`	Example
cronos	`v0.7.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-cronos-v0.7.0`	Example
cryptoorgchain	`v3.3.3`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-cryptoorgchain-v3.3.3`	Example
decentr	`v1.5.7`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-decentr-v1.5.7`	Example
defund	`v0.0.2`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-defund-v0.0.2`	Example
desmos	`v2.3.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-desmos-v2.3.1`	Example
dig	`v2.0.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-dig-v2.0.1`	Example
emoney	`v1.1.4`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-emoney-v1.1.4`	Example
evmos	`v7.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-evmos-v7.0.0`	Example
fetchhub	`v0.10.4`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-fetchhub-v0.10.4`	Example
gravitybridge	`v1.4.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-gravitybridge-v1.4.1`	Example
impacthub	`v0.17.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-impacthub-v0.17.0`	Example
irisnet	`v1.0.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-irisnet-v1.0.1`	Example
juno	`v9.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-juno-v9.0.0`	Example
kava	`v0.16.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-kava-v0.16.1`	Example
kixchain	`3.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-kichain-3.0.0`	Example
konstellation	`0.5.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-konstellation-0.5.0`	Example
kujira	`v0.5.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-kujira-v0.5.0`	Example
likecoin	`v3.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-likecoin-v3.0.0`	Example
lumnetwork	`v1.0.5`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-lumnetwork-v1.0.5`	Example
omniflixhub	`v0.4.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-omniflixhub-v0.4.1`	Example
osmosis	`v11.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-osmosis-v11.0.0`	Example
panacea	`v2.0.2`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-panacea-v2.0.2`	Example
passage	`v1.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-passage-v1.0.0`	Example
persistence	`v0.1.3`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-persistence-v0.1.3`	Example
regen	`v4.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-regen-v4.0.0`	Example
rizon	`v0.2.8`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-rizon-v0.2.8`	Example
seinetwork	`1.1.1beta`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-seinetwork-1.1.1beta`	Example
sentinel	`v0.8.3`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-sentinel-v0.8.3`	Example
shentu	`v2.2.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-shentu-v2.2.0`	Example
sifchain	`v0.15.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-sifchain-v0.15.0`	Example
sommelier	`v3.1.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-sommelier-v3.1.0`	Example
stargaze	`v5.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-stargaze-v5.0.0`	Example
starname	`v0.10.18`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-starname-v0.10.18`	Example
umee	`v1.0.1`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-umee-v1.0.1`	Example
vidulum	`v1.0.0`	`ghcr.io/ovrclk/cosmos-omnibus:v0.3.2-vidulum-v1.0.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.

Snaphots

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.

Akash also generate and publish snapshots for the Akash blockchain. Pruned snapshots are taken daily, and Archive snapshots weekly.

These snapshots are created using Omnibus nodes running on Akash, as shown in the Snapshot Backup example.

Type	Snapshot JSON
Akash Pruned	https://cosmos-snapshots.s3.filebase.com/akash/pruned/snapshot.json
Akash Archive	https://cosmos-snapshots.s3.filebase.com/akash/snapshot.json

Examples

See the _examples directory for some common setups, including:

Configuration

Cosmos blockchains can be configured entirely using environment variables instead of the config files. Every chain has it's own prefix, 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.

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.

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/ovrclk/net/master/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 peers.
Any ADDRBOOK_URL where the config/addrbook.json file is hosted.

See Cosmos docs for more information.

Variable	Description	Examples
`P2P_SEEDS`	Seed nodes. Can be set by CHAIN_JSON or GENESIS_URL	`id@node:26656`
`P2P_PERSISTENT_PEERS`	Persistent peers. Can be set by CHAIN_JSON or GENESIS_URL	`id@node:26656`
`P2P_POLKACHU`	Import live persistent peers from Polkachu if available	`1`
`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`
`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`
`STATESYNC_POLKACHU`	Import Polkachu's statesync addresses if available		`1`

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_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_POLKACHU`	Import Polkachu's snapshot automatically if available		`1`

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`
`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`

Shortcuts

See Cosmos docs for more information

Variable	Description	Examples
`FASTSYNC_VERSION`	The fastsync version	`v0`
`MINIMUM_GAS_PRICES`	Minimum gas prices	`0.025uakt`
`PRUNING`	How much of the chain to prune	`nothing`
`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:

Ideally source or setup a chain.json to provide a single source of truth for chain info
Add a project directory based on the existing projects
Update the github workflow to create an image for your chain

Submit a PR or an issue if you want to see any specific chains.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

COSMOS OMNIBUS - Run Cosmos Nodes on Akash

Generic image (binary downloaded at runtime)

Networks (pre-built images)

Example configurations

Running on Akash

Running locally/any docker host

Snaphots

Examples

Configuration

Chain configuration

P2P

Private key backup/restore

Statesync

Snapshot restore

Snapshot backup

Binary download

Shortcuts

Contributing

About

Releases

Packages

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 232 Commits
.github/workflows		.github/workflows
_examples		_examples
agoric		agoric
akash		akash
assetmantle		assetmantle
bandchain		bandchain
bitcanna		bitcanna
bitsong		bitsong
bostrom		bostrom
cerberus		cerberus
cheqd		cheqd
chihuahua		chihuahua
chronicnetwork		chronicnetwork
comdex		comdex
cosmoshub		cosmoshub
cronos		cronos
cryptoorgchain		cryptoorgchain
decentr		decentr
defund		defund
desmos		desmos
dig		dig
emoney		emoney
evmos		evmos
fetchhub		fetchhub
generic		generic
gravitybridge		gravitybridge
impacthub		impacthub
irisnet		irisnet
juno		juno
kava		kava
kichain		kichain
konstellation		konstellation
kujira		kujira
likecoin		likecoin
lumnetwork		lumnetwork
nomic		nomic
omniflixhub		omniflixhub
osmosis		osmosis
panacea		panacea
passage		passage
persistence		persistence
regen		regen
rizon		rizon
seinetwork		seinetwork
sentinel		sentinel
shentu		shentu
sifchain		sifchain
sommelier		sommelier
stargaze		stargaze
starname		starname
terra		terra
umee		umee
vidulum		vidulum
.editorconfig		.editorconfig
.env.sample		.env.sample
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
run.sh		run.sh
snapshot.sh		snapshot.sh

maxmaxlabs/cosmos-omnibus

Folders and files

Latest commit

History

Repository files navigation

COSMOS OMNIBUS - Run Cosmos Nodes on Akash

Generic image (binary downloaded at runtime)

Networks (pre-built images)

Example configurations

Running on Akash

Running locally/any docker host

Snaphots

Examples

Configuration

Chain configuration

P2P

Private key backup/restore

Statesync

Snapshot restore

Snapshot backup

Binary download

Shortcuts

Contributing

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages