Skip to content

sikkatech/cosmos-omnibus

 
 

Repository files navigation

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.

Additionally the node private keys can be backed up and restored from any S3 compatible storage provider, such as Sia or Storj, via Filebase.

Networks

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

Project Version Image
akash v0.12.1 ghcr.io/ovrclk/cosmos-omnibus:v0.0.6-akash-v0.12.1 Example
sentinelhub v0.7.0 ghcr.io/ovrclk/cosmos-omnibus:v0.0.6-sentinelhub-v0.7.0 Example
gaia v4.2.1 ghcr.io/ovrclk/cosmos-omnibus:v0.0.6-gaia-v4.2.1 Example
kava v0.14.2 ghcr.io/ovrclk/cosmos-omnibus:v0.0.6-kava-v0.14.2 Example
osmosis v3.1.0 ghcr.io/ovrclk/cosmos-omnibus:v0.0.6-osmosis-v3.1.0 Example
persistence v0.1.3 ghcr.io/ovrclk/cosmos-omnibus:v0.0.6-persistence-v0.1.3 Example
juno lucina ghcr.io/ovrclk/cosmos-omnibus:v0.0.6-juno-lucina Example
regen v1.0.0 ghcr.io/ovrclk/cosmos-omnibus:v0.0.6-regen-v1.0.0 Example

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 docker-compose.yml files in each project directory.

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

Chain configuration

Chain config can be sourced from a chain.json file as implemented by @sikkatech, or from a metadata repository such as Akash's ovrclk/net.

Variable Description Default Examples
CHAIN_URL URL to a chain.json file detailing the chain meta https://github.com/sikkatech/tm-networks/blob/master/akashnet-2/chain.json
METADATA_URL URL to a net repo in the same form as Akash https://github.com/ovrclk/net/tree/master/mainnet
CHAIN_ID The cosmos chain ID akashnet-2
GENESIS_URL URL to the genesis file in .gz or .zip format. Can be set by CHAIN_URL or METADATA_URL https://raw.githubusercontent.com/ovrclk/net/master/mainnet/genesis.json
VALIDATE_GENESIS Set to 0 to disable validation of genesis file 1 0

P2P

See Cosmos docs for more information. Note this can be sourced from CHAIN_URL or METADATA_URL automatically.

Variable Description Default Examples
P2P_SEEDS Seed nodes. Can be set by CHAIN_URL or GENESIS_URL id@node:26656
P2P_PERSISTENT_PEERS Persistent peers. Can be set by CHAIN_URL or GENESIS_URL id@node:26656

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

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
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 TRUSTED_NODE or first STATESYNC_RPC_SERVERS
STATESYNC_TRUST_HASH Obtained from TRUSTED_NODE or first STATESYNC_RPC_SERVERS

Snapshot restore

The node data directory can be restored from a .tar or .tar.gz file stored on a public URL. This can be from a specific URL, or from a base URL and a file matching a given pattern.

Variable Description Default Examples
BOOTSTRAP Whether to bootstrap the node from the snapshot URL 1 0
SNAPSHOT_URL A URL to a .tar or .tar.gz file http://135.181.60.250/akash/akashnet-2_2021-06-16.tar
SNAPSHOT_FORMAT The format of the snapshot file tar.gz tar
SNAPSHOT_BASE_URL A base URL to a directory containing backup files http://135.181.60.250/akash
SNAPSHOT_PATTERN The pattern of the file in the BASE_URL $CHAIN_ID.*$SNAPSHOT_FORMAT foobar.*tar.gz

Shortcuts

See Cosmos docs for more information

Variable Description Default Examples
FASTSYNC_VERSION The fastsync version v2
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 1

Running on Akash

See the deploy.yml example file in each chain directory which details the minimum configuration required. Use the above configuration options to add functionality.

Running locally

See the docker-compose.yml example file to run each node locally using docker-compose up

Examples

See the _examples directory for some common setups, including:

TODO

  • Backup node data to S3 on schedule
  • More chains..

Contributing

Adding a new chain is easy:

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

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

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Shell 76.7%
  • Dockerfile 23.3%