From 84ceadc25dfd28a2a5b70b4b8ff8cd1855560f75 Mon Sep 17 00:00:00 2001 From: corver Date: Fri, 11 Oct 2024 10:07:46 +0200 Subject: [PATCH] docs(*): improve readme and operator docs (#2144) Improve the raedme and the `Configure a Full Node` doc. issue: #2114 --- Makefile | 1 + README.md | 20 +++---- docs/content/operate/1-run-full-node.md | 38 +++++++------ docs/content/operate/3-uluwatu.md | 2 +- docs/content/operate/6-config.md | 72 ++++++++++++++----------- 5 files changed, 71 insertions(+), 62 deletions(-) diff --git a/Makefile b/Makefile index 6d0f144c6..94a996b7f 100644 --- a/Makefile +++ b/Makefile @@ -9,6 +9,7 @@ ARCH := $(shell arch | sed 's/x86_64/amd64/') .PHONY: build-docker build-docker: ensure-go-releaser ## Builds the docker images using local arch. + @git config --local core.abbrev 7 @sed "s/amd64/$(ARCH)/g" .goreleaser-snapshot.yaml > .goreleaser-local.yaml @goreleaser release -f .goreleaser-local.yaml --snapshot --clean --skip=archive @rm .goreleaser-local.yaml diff --git a/README.md b/README.md index 76d0be01e..a6ed5db25 100644 --- a/README.md +++ b/README.md @@ -39,30 +39,22 @@ The [Omni Docs](https://docs.omni.network/) are the best place to get started le ## Quickstart -Building the node requires a working Go (version 1.22 or higher, see `go.mod`) and `goreleaser` ([see installation guide here](https://goreleaser.com/install/) or install with `make ensure-go-releaser`). You can install them using your favorite package manager. Once the dependencies are installed, run: +Ensure [go](https://go.dev/doc/install), [goreleaser](https://goreleaser.com/install/) and [docker](https://docs.docker.com/engine/install/) are installed. ```bash +# Build local docker containers make build-docker -``` - -To run the end-to-end tests, run: -```bash +# Run the end-to-end tests on a local devnet MANIFEST=devnet1 make e2e-run -``` -_If the above command fails, [see the troubleshooting section](./e2e/README.md#troubleshooting)._ - -To start a devnet, run: -```bash +# Start a local devnet make devnet-deploy -``` -To stop it, run: - -```bash +# Stop the local devnet make devnet-clean ``` +_If any of above commands fail, see the [troubleshooting section](./e2e/README.md#troubleshooting)._ ## Directory Structure diff --git a/docs/content/operate/1-run-full-node.md b/docs/content/operate/1-run-full-node.md index 8311cbca1..559500b61 100644 --- a/docs/content/operate/1-run-full-node.md +++ b/docs/content/operate/1-run-full-node.md @@ -2,6 +2,8 @@ Currently, anyone can run a node on Omega Testnet. Stay tuned for running full nodes on mainnet. +Check out our latest [releases](https://github.com/omni-network/omni/releases/tag/latest). + ## Omni Omega Testnet ### Quick Start @@ -9,13 +11,13 @@ Currently, anyone can run a node on Omega Testnet. Stay tuned for running full n The simplest way to run a full node is with the following commands: ```bash -# Install the Omni CLI +# install the omni cli (or download https://github.com/omni-network/omni/releases/latest) curl -sSfL https://raw.githubusercontent.com/omni-network/omni/main/scripts/install_omni_cli.sh | sh -s -# init geth and halo -omni operator init-nodes --network=omega --moniker=foo --clean +# init halo and geth +omni operator init-nodes --network=omega --moniker=foo -# start geth and helo +# start halo and geth cd ~/.omni/omega docker compose up ``` @@ -25,19 +27,18 @@ Congrats, you're running a full node! ### Details #### What's actually happening here? - -- First, you're installing the `omni` cli. We've packaged up several flows into this CLI to make running a node easier for operators. -- The `init-nodes` command is used to generate genesis files and config files and docker compose in the `~/.omni/` directory. -- `docker compose up -d` spins up docker containers `halovisor` and `geth`. -- For detailed instructions on manually configuring a full node, see [Configure a Full Node](6-config.md) +- First, you're installing the `omni` CLI which contains tooling to manage a node. +- The `omni operator init-nodes` command generates config files, genesis files, and docker compose in `~/.omni/`. +- `docker compose up -d` spins up the `halovisor` and `geth` containers. #### What is the Omni Node software stack? - The Omni architecture is similar to Ethereum PoS in that it consists of two chains: an execution chain and a consensus chain. - The execution chain is implemented by running the latest version of `geth` . Note that Omni doesn’t fork geth, we use the stock standard version, just with a custom Omni execution genesis file. - The consensus chain is implemented by running `halo` which is a CosmosSDK application chain. Halo connects to geth via the [EngineAPI](https://geth.ethereum.org/docs/interacting-with-geth/rpc#engine-api). -- Running a Omni full node therefore consists of running both `halo` and `geth`. +- Running an Omni full node therefore consists of running both `halo` and `geth`. +- For step-by-step instructions to manually configuring a full node, see [Configure a Full Node](6-config.md) -#### Node Requirements +#### Hardware Requirements | Category | Recommendation | |------------------|------------------------------------------------------------------------------| @@ -49,19 +50,21 @@ Congrats, you're running a full node! | Operating System | `linux/amd64` | | Inbound ports | Enabled for cometBFT (`tcp://26656`) and Geth (`tcp://30303`, `udp://30303`) | -#### `halo` Deployment Instructions +#### `halo` Deployment Options Note that `halo` is a CosmosSDK application which requires a specific binary version to run at each network upgrade height. CosmosSDK uses [Cosmovisor](https://docs.cosmos.network/main/build/tooling/cosmovisor) to manage the binary versioning and swapping at the correct height. There are three ways to run `halo`, listed in order of preference: -1. **πŸ₯‡`omniops/halovisor:` docker container** - - Simply run the latest version of `halovisor` docker container. It will automatically detect and run the correct halo binary version using cosmovisor internally. +1. **πŸ₯‡ Halovisor docker container** + - Simply run the `omniops/halovisor:` docker container. + - It combines multiple `halo` versions with `cosmovisor` for automatic network upgrades. - E.g. `omniops/halovisor:v0.9.0` contains the `halo:v0.8.1` and `halo:v0.9.0` binaries and will automatically switch at the correct height. - It only requires a single docker volume mount: `-v ~/.omni//halo:/halo` - It will persist the cosmovisor β€œcurrent” binary symlink to: `halo/halovisor-current` -2. **πŸ₯ˆStandard Cosmovisor with `halo` binaries** + +2. **πŸ₯ˆ Cosmovisor with halo binaries** - Install and configure stock-standard CosmosSDK Cosmovisor with `halo` binaries, see docs [here](https://docs.cosmos.network/main/build/tooling/cosmovisor#setup) and [here](https://docs.archway.io/validators/running-a-node/cosmovisor) and [here](https://docs.junonetwork.io/validators/setting-up-cosmovisor). This will also automatically swap the β€œcurrent” binary at the correct height. - The binaries versions to use are: - `genesis: halo:v0.8.1` @@ -79,8 +82,9 @@ There are three ways to run `halo`, listed in order of preference: β”‚ β”œβ”€β”€ genesis/bin/$DEAMONNAME # halo:v0.8.1 β”‚ β”œβ”€β”€ upgrades/1_uluwatu/bin/$DEAMONNAME # halo:v0.9.0 ``` -3. **πŸ₯‰Manual binary/docker swapping** - - Swapping halo binary version manually is also an option. + +3. **πŸ₯‰ Manual binary/docker swapping** + - Swapping halo binary or docker version manually is also an option. - When `halo:v0.8.1` reaches the network upgrade height, it will stall. - Stop it, and replace it with `halo:v0.9.0` - Start the node and it should catch up and continue processing the chain. diff --git a/docs/content/operate/3-uluwatu.md b/docs/content/operate/3-uluwatu.md index b9359ef9f..8e7777908 100644 --- a/docs/content/operate/3-uluwatu.md +++ b/docs/content/operate/3-uluwatu.md @@ -22,6 +22,6 @@ The upgrade contains changes to `halo`’s `attest` module logic ensuring that a No changes to `geth` is required, this version is compatible with `v1.14.11`. -See [Run a Full Node](./1-run-full-node.md#halo-deployment-instructions) for more details on running `halo` with `cosmovisor`. +See [Run a Full Node](./1-run-full-node.md#halo-deployment-options) for more details on running `halo` with `cosmovisor`. See the [Operator FAQ](./5-faq.md) for details on `halovisor vs halo` and `docker vs binaries` diff --git a/docs/content/operate/6-config.md b/docs/content/operate/6-config.md index c35127c28..e0764a35a 100644 --- a/docs/content/operate/6-config.md +++ b/docs/content/operate/6-config.md @@ -1,31 +1,43 @@ # Configure a Full Node -This document provides a detailed step-by-step process describing how to manually -reproduce what the `omni operators init-nodes` command does automatically. +This document provides a detailed step-by-step process describing how to manually setup and configure an Omni node. +It reproduces what the `omni operators init-nodes` command does automatically. See [Run a Full Node](1-run-full-node.md) docs for the automated process. -Note that validator nodes require additional config as specified in the [Run a Validator](2-validator.md) docs. +The resulting `~/.omni/` folder has the following structure: +``` +~/.omni// # Node home folder + β”œβ”€ halo/ # Consensus client + β”œβ”€ geth/ # Execution client + β”œβ”€ compose.yml # Docker compose +``` + +It is a valid configuration for running a production Omni full node. + +The only supported `` at the moment is: `omega` + +Note that validator nodes require additional config as specified in the [Run a Validator](2-validator.md). ## Configure halo Halo is a CosmosSDK application. Configuring it is therefore very similar to any -CosmosSDK application, learn more from their [Running a Node](https://docs.cosmos.network/main/user/run-node/run-node) docs. +CosmosSDK application, learn more from their [Running a Node](https://docs.cosmos.network/main/user/run-node/run-node). The `~/.omni//halo` folder has the following structure: ``` -. # ~/.omni//halo -β”œβ”€ config/ -β”‚ β”œβ”€β”€ halo.toml # Halo configuration file, similar to Cosmos app.toml -β”‚ β”œβ”€β”€ config.toml # Standard CometBFT configuration file -β”‚ β”œβ”€β”€ genesis.json # The consensus chain genesis file -β”‚ β”œβ”€β”€ node_key.json # Standard CometBFT P2P node identity key -β”‚ β”œβ”€β”€ priv_validator_key.json # Standard CometBFT consensus private key -β”œβ”€ data/ -β”‚ β”œβ”€ priv_validator_state.json # Standard CometBFT slashing DB (validator last signed state) -β”‚ β”œβ”€ voter_state.json # Omni xchain slashing DB (last signed state) +~/.omni//halo/ + β”œβ”€ config/ + β”‚ β”œβ”€β”€ halo.toml # Halo configuration file, similar to Cosmos app.toml + β”‚ β”œβ”€β”€ config.toml # Standard CometBFT configuration file + β”‚ β”œβ”€β”€ genesis.json # The consensus chain genesis file + β”‚ β”œβ”€β”€ node_key.json # Standard CometBFT P2P node identity key + β”‚ β”œβ”€β”€ priv_validator_key.json # Standard CometBFT consensus private key + β”œβ”€ data/ + β”‚ β”œβ”€ priv_validator_state.json # Standard CometBFT slashing DB (validator last signed state) + β”‚ β”œβ”€ voter_state.json # Omni xchain slashing DB (last signed state) ``` -#### halo.toml +### halo.toml `halo.toml` is Halo's CosmosSDK application configuration file. It is similar to the `app.toml` file in other CosmosSDK applications. It is located in `~/.omni//halo/config/halo.toml`. @@ -41,7 +53,7 @@ The following required fields are empty by default and must be populated: `config.toml` is the CometBFT configuration file. It is located in `~/.omni//halo/config/config.toml`. Learn more from CometBFT [docs](https://docs.cometbft.com/v0.38/core/configuration). -Download the latest default `config.toml` [here](https://github.com/omni-network/omni/blob/main/halo/cmd/testdata/default_config.toml). +Download the latest default omni `config.toml` [here](https://github.com/omni-network/omni/blob/main/halo/cmd/testdata/default_config.toml). Ensure the following fields are populated: - `moniker`: A custom human readable name for this node @@ -51,7 +63,7 @@ Ensure the following fields are populated: - `p2p.seeds`: Omni consensus seed nodes to connect to, see omega's [here](https://github.com/omni-network/omni/blob/main/lib/netconf/omega/consensus-seeds.txt). - `p2p.persistent_peers`: Can configure this with same seed nodes above. -#### Configure CometBFT State Sync +### Configure CometBFT State Sync When syncing a new full node from scratch, state sync can be configured to speed up the process. Learn more from the CometBFT docs [here](https://docs.cometbft.com/v0.34/core/state-sync). @@ -82,7 +94,7 @@ Then, configure state sync in `~/.omni//halo/config/config.toml`: `genesis.json` is the Omni consensus chain genesis file for the specific network (omega vs mainnet). It is located in `~/.omni//halo/config/genesis.json`. -Download the Omega testnet consensus `genesis.json` [here](https://github.com/omni-network/omni/blob/main/lib/netconf/omega/consensus-genesis.json). +Download the Omega consensus `genesis.json` [here](https://github.com/omni-network/omni/blob/main/lib/netconf/omega/consensus-genesis.json). ### node_key.json `node_key.json` is the CometBFT P2P node identity key. @@ -115,19 +127,19 @@ Learn more from the [geth docs](https://geth.ethereum.org/docs/fundamentals/conf The `~/.omni//geth` folder has the following structure: ``` -. # ~/.omni//geth -β”œβ”€ config.toml # Geth configuration file -β”œβ”€ genesis.json # The execution chain genesis file -β”œβ”€ geth/ -β”‚ β”œβ”€β”€ nodekey # Geth P2P node identity key -β”‚ β”œβ”€β”€ jwtsecret # Geth JWT secret file for auth RPC +~/.omni//geth + β”œβ”€ config.toml # Geth configuration file + β”œβ”€ genesis.json # The execution chain genesis file + β”œβ”€ geth/ + β”‚ β”œβ”€β”€ nodekey # Geth P2P node identity key + β”‚ β”œβ”€β”€ jwtsecret # Geth JWT secret file for auth RPC ``` ### config.toml `config.toml` is the geth configuration file. It is located in `~/.omni//geth/config.toml`. -Download the latest default `config.toml` [here](https://github.com/omni-network/omni/blob/main/e2e/app/geth/testdata/default_config.toml). +Download the latest default omni `config.toml` [here](https://github.com/omni-network/omni/blob/main/e2e/app/geth/testdata/default_config.toml). Ensure the following fields are populated: - `NetworkId`: Omni network ID; Omega testnet is `164`, mainnet is `165`. @@ -138,7 +150,7 @@ Ensure the following fields are populated: `genesis.json` is the Omni execution chain genesis file for the specific network (omega vs mainnet). It is located in `~/.omni//geth/genesis.json`. -Download the Omega testnet execution `genesis.json` [here](https://github.com/omni-network/omni/blob/main/lib/netconf/omega/execution-genesis.json). +Download the Omega execution `genesis.json` [here](https://github.com/omni-network/omni/blob/main/lib/netconf/omega/execution-genesis.json). `geth` **_MUST_** be initialized with this genesis file before starting for the first time, see geth [docs](https://geth.ethereum.org/docs/fundamentals/private-network#initializing-geth-database) to learn more: ```bash @@ -160,13 +172,13 @@ A path to this file (or copy of) must be provided in the `halo.toml` `engine-jwt `geth` will automatically generate this file during `geth init` on startup if it doesn't exist. ## Configure Docker Compose -The preferred way to run an Omni node is via Docker Compose as describe in the [Run a Full Node](1-run-full-node.md#halo-deployment-instructions) docs. -The docker `compose.yml` file is located in `~/.omni//`. +The preferred way to run an Omni node is via Docker Compose as describe in the [Run a Full Node](1-run-full-node.md#halo-deployment-options) docs. +The docker `compose.yml` file is located in `~/.omni//compose.yml`. Download the latest template `compose.yml` [here](https://github.com/omni-network/omni/blob/main/cli/cmd/compose.yml.tpl). Ensure the following template fields are replaced: -- `{{.HaloTag}}`: The latest release `omniops/halovisor` docker image tag, see [releases](https://github.com/omni-network/omni/releases) -- `{{.GethTag}}`: The `ethereum/client-go` version supported by the above omni release, see release notes. +- `{{.HaloTag}}`: The latest `omniops/halovisor` docker image tag, eg `v0.99.0`, see [releases](https://github.com/omni-network/omni/releases) +- `{{.GethTag}}`: The `ethereum/client-go` version supported by the above omni release, see release notes, e.g. `v1.99.0`. - `{{.GethVerbosity}}`: Geth logging level, `3` is recommended for info level. - `{{ if .GethArchive }}- --gcmode=archive{{ end }}`: Remove this line if not an archive node.