Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 21 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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
sudo adduser poktroll
sudo usermod -aG sudo poktroll
su - poktroll
```

## Retrieve the source code
Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
25 changes: 7 additions & 18 deletions docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
sudo adduser poktroll
sudo usermod -aG 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
Expand Down
147 changes: 55 additions & 92 deletions docusaurus/docs/operate/quickstart/full_node_cheatsheet.md
Original file line number Diff line number Diff line change
@@ -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 scripts.

:::tip

If you're interesting in understanding everything, or having full control of every
step, 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**:

Expand All @@ -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 interest in understand 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/`
Expand All @@ -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.

-->
6 changes: 3 additions & 3 deletions docusaurus/docs/operate/quickstart/gateway_cheatsheet.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 5
sidebar_position: 7
title: Gateway Cheat Sheet
---

Expand Down Expand Up @@ -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.

:::

Expand Down
9 changes: 5 additions & 4 deletions docusaurus/docs/operate/quickstart/service_cheatsheet.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 6
sidebar_position: 5
title: Service Cheat Sheet
---

Expand Down Expand Up @@ -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 \
Expand Down
30 changes: 30 additions & 0 deletions docusaurus/docs/operate/quickstart/validator_cheatsheet.md
Original file line number Diff line number Diff line change
@@ -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 scripts.

:::tip

If you're interesting 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 helper 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
Loading
Loading