docs(*): improve readme and operator docs (#2144)

Improve the raedme and the `Configure a Full Node` doc.

issue: #2114

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

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
 

docs/content/operate/1-run-full-node.md

@@ -2,20 +2,22 @@
 
 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
 
 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/<network>` 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/<network>`.
+- `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:<latest>` 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:<latest>` 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/<network>/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.

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`

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/<network>` folder has the following structure:
+```
+~/.omni/<network>/     # 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 `<network>` 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/<network>/halo` folder has the following structure:
 ```
-.                              # ~/.omni/<network>/halo
-├─ config/
-│ ├── halo.toml                # Halo configuration file, similar to Cosmos app.toml
-│ ├── config.toml              # Standard CometBFT configuration file
-│ ├── genesis.json             # The <network> 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/<network>/halo/
+ ├─ config/
+ │ ├── halo.toml                # Halo configuration file, similar to Cosmos app.toml
+ │ ├── config.toml              # Standard CometBFT configuration file
+ │ ├── genesis.json             # The <network> 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/<network>/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/<network>/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/<network>/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/<network>/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/<network>/geth` folder has the following structure:
 ```
-.                             # ~/.omni/<network>/geth
-├─ config.toml                # Geth configuration file
-├─ genesis.json               # The <network> execution chain genesis file
-├─ geth/
-│ ├── nodekey                 # Geth P2P node identity key
-│ ├── jwtsecret               # Geth JWT secret file for auth RPC
+~/.omni/<network>/geth
+ ├─ config.toml                # Geth configuration file
+ ├─ genesis.json               # The <network> 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/<network>/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/<network>/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/<network>/`.
+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/<network>/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.