[Docs] Full Node Documentation Update (#941 followup) (#981)

## Summary - Improvements to the Full Node walkthrough + cheatsheet - A handful of other miscleanious changes to make the docs more "holistic" - Prep for the validator cheatsheets - ## Issue - Followup to #941 ## Type of change Select one or more from the following: - [ ] New feature, functionality or library - [ ] Consensus breaking; add the `consensus-breaking` label if so. See #791 for details - [ ] Bug fix - [ ] Code health or cleanup - [x] Documentation - [ ] Other (specify) --------- Co-authored-by: Redouane Lakrache <[email protected]>
pokt-network · Dec 5, 2024 · 4865278 · 4865278
1 parent a9ad5e8
commit 4865278
Show file tree

Hide file tree

Showing 10 changed files with 365 additions and 275 deletions.
diff --git a/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md b/docusaurus/docs/operate/quickstart/docker_compose_debian_cheatsheet.md
@@ -89,9 +89,9 @@ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin
 You can optionally create a new user and give it sudo permissions instead of using `root`.
 
 ```bash
-export USERNAME=olshansky
-sudo adduser $USERNAME
-sudo usermod -aG sudo $USERNAME
+adduser poktroll
+usermod -aG docker,sudo poktroll
+su - poktroll
 ```
 
 ## Retrieve the source code
@@ -114,9 +114,9 @@ cp .env.sample .env
 
 By default, the `.env` file uses `testnet-beta`. If you want to use a different network, update the `NETWORK_NAME` in your `.env` file to one of:
 
-- `testnet-alpha` - Unstable testnet
-- `testnet-beta` - Stable testnet (default)
-- `mainnet` - Production network
+- `testnet-alpha`: Unstable testnet (use at your own risk)
+- `testnet-beta`: Stable testnet (default)
+- `mainnet`: Production network (not launched yet)
 
 Then set your external IP and source the environment:
 
@@ -179,7 +179,7 @@ FINALLY, `source .env` to update the environment variables.
 
 ## Fund your accounts
 
-Run the following to see your addresses:
+Run the following helper command to see your addresses:
 
 ```bash
 show_actor_addresses
@@ -191,7 +191,8 @@ Get the faucet URL for your network:
 show_faucet_url
 ```
 
-Fund each address using the faucet URL shown above. Then run this helper to find each account on the explorer:
+Fund each address using the faucet URL shown above.
+Then run this helper to find each account on the explorer:
 
 ```bash
 show_explorer_urls

diff --git a/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md b/docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md
@@ -152,40 +152,29 @@ Update `NODE_HOSTNAME` in `.env` to the IP address or hostname of your node. For
 sed -i -e s/NODE_HOSTNAME=/NODE_HOSTNAME=69.42.690.420/g .env
 ```
 
-### [Optional] Create a new user <!-- omit in toc -->
-
-:::note
-
-Make sure to replace `olshansky` with your username.
-
-:::
+### [Recommended] Create a new user <!-- omit in toc -->
 
 You can generally do everything as the `root` user, but it's recommended to
 create a new user and give it sudo permissions.
 
 This is necessary, in particular, if you want to use [homebrew](https://brew.sh/) [to install `poktrolld`](../user_guide/install.md).
 
-```bash
-# Create a new user and give sudo permissions
-export USERNAME=olshansky
-sudo adduser $USERNAME
-sudo usermod -aG sudo $USERNAME
-```
-
-Then, switch to the new user:
+You can create a new user (e.g. poktroll), provide sudo permissions and switch users like so:
 
 ```bash
-su - olshansky
+adduser poktroll
+sudo usermod -aG docker,sudo poktroll
+su - poktroll
 ```
 
-You can also avoid needing to pass in the password each time by running the following:
+In order to avoid needing to pass in the password each time by running the following:
 
 ```bash
 # Optionally avoid needing to provide a password
 sudo vi /etc/sudoers
 
 # Add the following line to the end of the file
-olshansky ALL=(ALL) NOPASSWD:ALL
+poktroll ALL=(ALL) NOPASSWD:ALL
 ```
 
 ## A. Deploying a Full Node

diff --git a/docusaurus/docs/operate/quickstart/full_node_cheatsheet.md b/docusaurus/docs/operate/quickstart/full_node_cheatsheet.md
@@ -1,31 +1,48 @@
 ---
-sidebar_position: 3
 title: Full Node Cheat Sheet
+sidebar_position: 3
 ---
 
-This cheat sheet provides quick instructions for installing a Full Node using an automated script.
+## Full Node Cheat Sheet Using Systemd & Cosmovisor <!-- omit in toc -->
+
+This cheat sheet provides quick copy-pasta like instructions for installing and
+running a Full Node using an automated script.
+
+:::tip
 
+If you're interested in understanding the underlying details, or having full control over every
+step of the process, check out the [Full Node Walkthrough](../run_a_node/full_node_walkthrough.md).
+
+:::
+
+- [Introduction](#introduction)
 - [Pre-Requisites](#pre-requisites)
-- [Install a Full Node using Cosmovisor](#install-a-full-node-using-cosmovisor)
-- [What Gets Installed](#what-gets-installed)
-- [Useful Commands](#useful-commands)
-  - [Check the status of your node](#check-the-status-of-your-node)
-  - [View the logs](#view-the-logs)
-  - [Stop the node](#stop-the-node)
-  - [Start the node](#start-the-node)
-  - [Restart the node](#restart-the-node)
-  - [Advanced Operations](#advanced-operations)
-- [Automatic Upgrades](#automatic-upgrades)
+- [Install and Run a Full Node using Cosmovisor](#install-and-run-a-full-node-using-cosmovisor)
+  - [Automatic Upgrades Out of the Box](#automatic-upgrades-out-of-the-box)
+- [FAQ \& Troubleshooting](#faq--troubleshooting)
+- [\[OPTIONAL\] Do you care to know what just happened?](#optional-do-you-care-to-know-what-just-happened)
+
+### Introduction
+
+This guide will help you install a Full Node for Pocket Network,
+**using helper that abstract out some of the underlying complexity.**
+
+Running a Full Node is the first step toward becoming a Validator, Supplier, or Gateway.
 
 ### Pre-Requisites
 
 1. **Linux-based System**: Ensure you have a Debian-based Linux distribution (other distributions may work but are not fully supported).
 2. **Root or Sudo Access**: You need administrative privileges to run the installation script.
 3. **Dedicated Server or Virtual Machine**: Any provider should work (Vultr and Hetzner have been tested).
 
-### Install a Full Node using Cosmovisor
+### Install and Run a Full Node using Cosmovisor
+
+:::info
+This section script will handle the installation of dependencies, user creation,
+environment variable setup, and configuration of Cosmovisor and `poktrolld`.
+:::
 
-To install and set up a Full Node, follow these steps:
+Follow the instructions below to **quickly** install and set up a Full Node:
 
 1. **Download the Installation Script**:
 
@@ -43,24 +60,44 @@ To install and set up a Full Node, follow these steps:
 
    - **Choose the Network**: Select `testnet-alpha`, `testnet-beta`, or `mainnet`.
    - **Set Username**: Input the desired username to run `poktrolld` (default: `poktroll`).
-   - **Set Node Moniker**: Input the node moniker (default: your hostname).
+   - **Set Node Moniker**: Input the node moniker (default: your `hostname`).
    - **Confirm Seeds and Genesis File**: The script fetches seeds and the genesis file automatically.
    - **External IP Address**: The script detects your external IP address. Confirm or input manually if incorrect.
 
-The script will handle the installation of dependencies, user creation, environment variable setup, and configuration of Cosmovisor and `poktrolld`.
+#### Automatic Upgrades Out of the Box
 
-### What Gets Installed
+Your node is configured to handle chain upgrades automatically through Cosmovisor. No manual intervention is required for standard upgrades.
 
-When you run the installation script, the following components are set up:
+When a chain upgrade is proposed and approved:
+
+1. Cosmovisor will download the new binary
+2. The node will stop at the designated upgrade height
+3. Cosmovisor will switch to the new binary
+4. The node will restart automatically
+
+### FAQ & Troubleshooting
+
+See the [FAQ & Troubleshooting section in the Full Node Walkthrough](../run_a_node/full_node_walkthrough.md#faq--troubleshooting)
+for examples of useful commands, common debugging instructions and other advanced usage.
+
+### [OPTIONAL] Do you care to know what just happened?
+
+:::info
+This section is optional and for informational purposes only.
+:::
+
+If you're interested in understanding what just got installed, keep reading...
 
 1. **System User**: A dedicated user (default: `poktroll`) is created to run the node securely.
 
 2. **Cosmovisor**: A binary manager that handles chain upgrades automatically:
+
    - Location: `/home/poktroll/bin/cosmovisor`
    - Purpose: Manages different versions of `poktrolld` and handles chain upgrades
    - Configuration: Set up to automatically download and switch to new binaries during upgrades
 
 3. **Poktrolld**: The core node software:
+
    - Location: `/home/poktroll/.poktroll/cosmovisor/genesis/bin/poktrolld`
    - Configuration: `/home/poktroll/.poktroll/config/`
    - Data: `/home/poktroll/.poktroll/data/`
@@ -69,77 +106,3 @@ When you run the installation script, the following components are set up:
    - Name: `cosmovisor.service`
    - Status: Enabled and started automatically
    - Configured for automatic restarts and upgrades
-
-### Useful Commands
-
-After installation, you can manage your node using the following commands:
-
-#### Check the status of your node
-
-```bash
-sudo systemctl status cosmovisor.service
-```
-
-#### View the logs
-
-```bash
-sudo journalctl -u cosmovisor.service -f
-```
-
-#### Stop the node
-
-```bash
-sudo systemctl stop cosmovisor.service
-```
-
-#### Start the node
-
-```bash
-sudo systemctl start cosmovisor.service
-```
-
-#### Restart the node
-
-```bash
-sudo systemctl restart cosmovisor.service
-```
-
-#### Advanced Operations
-
-Check the current version:
-```bash
-sudo -u poktroll poktrolld version
-```
-
-View the Cosmovisor directory structure:
-```bash
-ls -la /home/poktroll/.poktroll/cosmovisor/
-```
-
-Check if an upgrade is available:
-```bash
-ls -la /home/poktroll/.poktroll/cosmovisor/upgrades/
-```
-
-View node configuration:
-```bash
-cat /home/poktroll/.poktroll/config/config.toml
-```
-
-### Automatic Upgrades
-
-Your node is configured to handle chain upgrades automatically through Cosmovisor. When a chain upgrade is proposed and approved:
-
-1. Cosmovisor will download the new binary
-2. The node will stop at the designated upgrade height
-3. Cosmovisor will switch to the new binary
-4. The node will restart automatically
-
-No manual intervention is required for standard upgrades.
-
-<!-- 
-## Becoming a Validator
-
-TODO(@okdas, #754): Add instructions for becoming a validator.
-
--->
diff --git a/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md b/docusaurus/docs/operate/quickstart/gateway_cheatsheet.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 7
 title: Gateway Cheat Sheet
 ---
 
@@ -91,8 +91,8 @@ export APP_ADDR=$(poktrolld keys show application -a)
 
 :::tip
 
-You can put the above in a special `~/.pocketrc` and add `source ~/.pocketrc` to
-your `~/.bashrc` file for a cleaner organization.
+You can put the above in a special `~/.poktrollrc` and add `source ~/.poktrollrc` to
+your `~/.profile` file for a cleaner organization.
 
 :::
 

diff --git a/docusaurus/docs/operate/quickstart/service_cheatsheet.md b/docusaurus/docs/operate/quickstart/service_cheatsheet.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 5
 title: Service Cheat Sheet
 ---
 
@@ -60,21 +60,22 @@ Here is an example of the output on Beta TestNet as of writing this document:
 You can use the `add-service` command to create a new service like so:
 
 ```bash
-poktrolld tx service add-service ${SERVICE_ID} "${SERVICE_NAME_OR_DESCRIPTION}" ${COMPUTE_UNITS_PER_RELAY} --from ${SERVICE_OWNER}
+poktrolld tx service add-service ${SERVICE_ID} "${SERVICE_NAME_OR_DESCRIPTION}" ${COMPUTE_UNITS_PER_RELAY} \
+  --fees 1upokt --from ${SERVICE_OWNER} --chain-id ${CHAIN_ID}
 ```
 
 Here is a concrete copy-pasta assuming you have created and funded a new account called `$USER`:
 
 ```bash
-poktrolld tx service add-service "svc-$USER" "service description for $USER" 69 \
+poktrolld tx service add-service "svc-$USER" "service description for $USER" 13 \
     --node https://shannon-testnet-grove-rpc.beta.poktroll.com \
     --fees 1upokt --from $USER --chain-id pocket-beta
 ```
 
 Optionally, you can add some more flags to be ultra-verbose about your local environment:
 
 ```bash
-poktrolld tx service add-service "svc-$USER" "service description for $USER" 69 \
+poktrolld tx service add-service "svc-$USER" "service description for $USER" 13 \
     --node https://shannon-testnet-grove-rpc.beta.poktroll.com \
     --fees 1upokt --from $USER --chain-id pocket-beta \
     --home ~/.poktroll --keyring-backend test \

diff --git a/docusaurus/docs/operate/quickstart/validator_cheatsheet.md b/docusaurus/docs/operate/quickstart/validator_cheatsheet.md
@@ -0,0 +1,30 @@
+---
+title: Validator Cheat Sheet
+sidebar_position: 4
+---
+
+## Validator Cheat Sheet <!-- omit in toc -->
+
+<!-- TODO_MAINNET(@okdas, #754): Update this page with all the details. -->
+
+This cheat sheet provides quick copy-pasta like instructions for installing and
+running a Validator using an automated script.
+
+:::tip
+
+If you're interested in understanding everything, or having full control of every
+step, check out the [Validator Walkthrough](../run_a_node/validator_walkthrough.md).
+
+:::
+
+- [Introduction](#introduction)
+  - [Pre-Requisites](#pre-requisites)
+
+## Introduction
+
+This guide will help you install a Validator on Pocket Network,
+**using helpers that abstract out some of the underlying complexity.**
+
+### Pre-Requisites
+
+1. **Run a Full Node**: Make sure you have followed the [Full Node Cheat Sheet](../quickstart/full_node_cheatsheet.md) to install and run a Full Node first