TERP O-Line - Run Terp Network Nodes on Akash

Make deploying Terp Network nodes onto Akash easy and standardized.

The goal is to have a simple way to launch with a variety of different bootstrapping options.

1. "normal" boostrap - using fastsync.
2. Hand-made 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)

O-line 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 O-Line primarily supports.

This generic image provides the O-line 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/terp-network/o-line:v0.0.12-generic

services:
  node:
    image: ghcr.io/terpnetwork/o-line:v0.0.12-generic
    env:
      - MONIKER=my-moniker-1
      - CHAIN_JSON=https://raw.githubusercontent.com/cosmos/chain-registry/refs/heads/master/terpnetwork/chain.json
      - BINARY_ZIP_PATH=terp_core_linux_amd64

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
terp-network	v4.2.2	terpnetwork/o-line:v0.0.12	Example

Example configurations

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. Note that the release images only supports amd64 platforms. You will have to manually compile the o-line image for the arm64 platform.

Snapshots

O-Line can import chain snapshots from almost any location.

Appropriate snapshot configuration is included in most example configurations in the O-Line 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 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 Terp Network:

TERP_P2P_SEEDS=id@node:26656

The o-line 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://raw.githubusercontent.com/terpnetwork/networks/main/mainnet/morocco-1/genesis.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/terp/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.

• 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 or GENESIS_URL		id@node:26656
P2P_PERSISTENT_PEERS	Persistent peers. Can be set by CHAIN_JSON or GENESIS_URL		id@node:26656
ADDRBOOK_URL	URL to an addrbook.json file		https://server-3.itrocket.net/mainnet/terp/addrbook.json

Statesync

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

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

Variable	Description	Default	Examples
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	terpd
PROJECT_DIR	Name of project directory	.$PROJECT_BIN	.terp

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.5.0
COSMOVISOR_URL	Alternative full URL to Cosmovisor binary tar.gz

Shortcuts

See Cosmos docs for more information

Variable	Description	Default	Examples
FASTSYNC_VERSION	The fastsync version		v0
MINIMUM_GAS_PRICES	Minimum gas prices		0.025uthiol
PRUNING	How much of the chain to prune		nothing
PRUNING_CUSTOM	custom pruning options		1
DEBUG	Set to 1 to output all environment variables on boot. Set to 2 to debug shell scripts.		1, 2

Contributing

Creating New ghcr.io image:

git tag v0.0.12 && git push --tags