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

Merged
merged 32 commits into from
Dec 5, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
f1f6136
WIP - Supplier cheatsheet
Olshansk Nov 21, 2024
98c3a89
WIP
Olshansk Nov 22, 2024
6303665
[Docs] Update links to RPC & explorers (#950)
Olshansk Nov 21, 2024
bd24703
Merge branch 'main' into supplier_cheatsheet
Olshansk Nov 25, 2024
f88ca87
Saving some old WIP
Olshansk Nov 25, 2024
2db06ee
Removed configs that sholdn't have been commited
Olshansk Nov 25, 2024
9ce8b2f
Finishing the service cheatsheet
Olshansk Nov 25, 2024
65a825d
Merge branch 'main' into service_cheasheet
Olshansk Nov 25, 2024
9fa7461
self review
Olshansk Nov 25, 2024
d952e5c
self review
Olshansk Nov 25, 2024
3b3c78e
Add back the supplier cheatsheet
Olshansk Nov 25, 2024
0c0794b
self review
Olshansk Nov 25, 2024
b1c22f8
Merge branch 'service_cheasheet' into supplier_cheatsheet
Olshansk Nov 25, 2024
fefd306
Adding the supplier cheatsheet back
Olshansk Nov 25, 2024
081f13f
Checkpoint
Olshansk Nov 26, 2024
6d2edc4
Merge with main
Olshansk Nov 26, 2024
9aed445
Merge branch 'main' into supplier_cheatsheet
Olshansk Dec 3, 2024
c293e09
Checkpoint - reviewing full node configs
Olshansk Dec 4, 2024
b0c00cf
Finish reviewing the full node walkthrough
Olshansk Dec 4, 2024
10c6598
Update the cheatsheet
Olshansk Dec 4, 2024
c2a22ac
rm supplier docs
Olshansk Dec 4, 2024
9107add
Merge branch 'main' into full_node_docs_update
Olshansk Dec 5, 2024
aa983e5
Update docusaurus/docs/operate/quickstart/docker_compose_walkthrough.md
Olshansk Dec 5, 2024
07a51e9
Update docusaurus/docs/operate/quickstart/validator_cheatsheet.md
Olshansk Dec 5, 2024
0648db9
Update docusaurus/docs/operate/quickstart/docker_compose_debian_cheat…
Olshansk Dec 5, 2024
816c54b
Update docusaurus/docs/operate/quickstart/validator_cheatsheet.md
Olshansk Dec 5, 2024
839b4f2
Update docusaurus/docs/operate/quickstart/validator_cheatsheet.md
Olshansk Dec 5, 2024
2b2c04f
Update docusaurus/docs/operate/run_a_node/full_node_walkthrough.md
Olshansk Dec 5, 2024
00d7e4b
Update docusaurus/docs/operate/quickstart/full_node_cheatsheet.md
Olshansk Dec 5, 2024
d3a0120
Update docusaurus/docs/operate/quickstart/full_node_cheatsheet.md
Olshansk Dec 5, 2024
d771e08
Update docusaurus/docs/operate/quickstart/full_node_cheatsheet.md
Olshansk Dec 5, 2024
0a3d78d
Add TODOs based on red0ne's feedback
Olshansk Dec 5, 2024
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
adduser poktroll
usermod -aG docker,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
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
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 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**:

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 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/`
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 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
Loading
Loading