Skip to main content

Docker Compose Walkthrough

Introduction and Cheat Sheet​

This document uses the poktroll-docker-compose-example to help stake and deploy every actor in the Pocket Network ecosystem.

It also provides some intuition for those already familiar with Morse and are transitioning to Shannon.

tip

This document has a lot of details and explanations. If you're looking for a copy-paste quickstart guide to set all of it up on a Debian server, check out the Debian cheat sheet.

This is a text heavy walkthrough, but if all goes well, you should have something like the following:

Key Terms in Morse and Shannon​

  • Morse - The current version of the Pocket Network MainNet (a.k.a v0).
  • Shannon - The upcoming version of the Pocket Network MainNet (a.k.a v1).
  • Validator - A node that participates in the consensus process.
    • In MorseSame in Morse and Shannon.
    • In Shannon
  • Node - A Morse actor that stakes to provide Relay services.
    • In Morse - All Validator are nodes but only the top 1000 stakes Nodes are Validators
    • This actor is not present in Shannon and decoupled into Supplier and a RelayMiner.
  • Supplier - The on-chain actor that stakes to provide Relay services.
    • In Shannon - This actor is responsible needs access to a Full Node (sovereign or node).
  • RelayMiner - The off-chain service that provides Relay services on behalf of a Supplier.
    • In Shannon - This actor is responsible for providing the Relay services.
  • PATH Gateway - The off-chain service that provides Relay services on behalf of an Application or Gateway.

For more details, please refer to the Shannon actors documentation.

Understanding Actors in the Shannon upgrade​

For those familiar with Morse, Pocket Network Mainnet, the introduction of multiple node types in the upcoming Shannon requires some explanation.

In Shannon, the Supplier role is separated from the Full node role.

In Morse, a Validator or a staked Node was responsible for both holding a copy of the on-chain data, as well as performing relays. With Shannon, the RelayMiner software, which runs the supplier logic, is distinct from the full-node/validator.

Furthermore, Shannon uses PATH Gateway, a software component that acts on behalf of either Applications or Gateways to access services provided by Pocket Network Suppliers via RelayMiners.

The following diagram from the actors page captures the relationship between on-chain records (actors) and off-chain operators (servers).

Prerequisites​

Note: the system must be capable of exposing ports to the internet for peer-to-peer communication.

Software & Tooling ​

Ensure the following software is installed on your system:

[Optional] Create a new user ​

note

Make sure to replace olshansky with your username.

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 to install poktrolld.

adduser poktroll
usermod -aG docker,sudo poktroll
su - poktroll

You can also avoid needing to pass in the password each time by running the following:

# Optionally avoid needing to provide a password
vi /etc/sudoers

# Add the following line to the end of the file
poktroll ALL=(ALL) NOPASSWD:ALL

Then, switch to the new user:

su - $USERNAME

Clone the Repository ​

git clone https://github.com/pokt-network/poktroll-docker-compose-example.git
cd poktroll-docker-compose-example

Operational Helpers ​

Run the following command, or add it to your ~/.bashrc to have access to helpers:

source helpers.sh

Environment Variables ​

Create and configure your .env file from the sample:

cp .env.sample .env

Update NODE_HOSTNAME in .env to the IP address or hostname of your node. For example:

sed -i -e s/NODE_HOSTNAME=/NODE_HOSTNAME=69.42.690.420/g .env

[Recommended] Create a new user ​

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 to install poktrolld.

You can create a new user (e.g. poktroll), provide sudo permissions and switch users like so:

adduser poktroll
sudo usermod -aG docker,sudo poktroll
su - poktroll

In order to avoid needing to pass in the password each time by running the following:

# Optionally avoid needing to provide a password
sudo vi /etc/sudoers

# Add the following line to the end of the file
poktroll ALL=(ALL) NOPASSWD:ALL

A. Deploying a Full Node​

Launch the Node ​

warning

The Alpha TestNet currently requires manual steps to sync the node to the latest block. Please find the affected block(s) in this document, which leads to the manual upgrade instructions.

Note: You may need to replace docker compose with docker-compose if you are running an older version of Docker where docker-compose is not integrated into docker itself yet.

Initiate the node with:

docker compose up -d full-node

Monitor node activity through logs with:

docker compose logs -f --tail 100 full-node

Inspecting the Full Node ​

If you run docker ps, you should see a full-node running which you can inspect using the commands below.

CometBFT Status ​

curl -s -X POST localhost:26657/status | jq

gRPC ​

To inspect the gRPC results on port 9090 you may install grpcurl.

Once installed:

grpcurl -plaintext localhost:9090 list

Latest Block ​

curl -s -X POST localhost:26657/block | jq

Watch the height ​

watch -n 1 "curl -s -X POST localhost:26657/block | jq '.result.block.header.height'"

You can compare the height relative to the shannon testnet explorer.

Get a way to fund your accounts ​

Throughout these instructions, you will need to fund your account with tokens at multiple points in time.

3.1 Funding using a Faucet ​

When you need to fund an account, you can make use of the Faucet.

[Requires Grove Team Support] 3.2 Funding using faucet account ​

If you require a larger amount of tokens or are a core contributor, you can add the faucet account to fund things yourself directly.

poktrolld keys add --recover -i faucet

When you see the > Enter your bipmnemonic prompt, paste the mnemonic provided by the Pocket team for testnet.

When you see the > Enter your bippassphrase. This is combined with the mnemonic to derive the seed. Most users should just hit enter to use the default, "" prompt, hit enter without adding a passphrase. Finish funding your account by using the command below:

You can view the balance of the faucet address at shannon.beta.testnet.pokt.network/.

Restarting a full node after re-genesis ​

If the team has completed a re-genesis, you will need to wipe existing data and restart your node from scratch. The following is a quick and easy way to start from a clean slate:


# Stop & remove existing containers
docker compose down
docker rm $(docker ps -aq) -f

# Remove existing data and renew genesis
rm -rf poktrolld-data/config/addrbook.json poktrolld-data/config/genesis.json poktrolld-data/config/genesis.seeds poktrolld-data/data/ poktrolld-data/cosmovisor/ poktrolld-data/config/node_key.json poktrolld-data/config/priv_validator_key.json

# Re-start the node
docker compose up -d
docker compose logs -f --tail 100

Docker image updates ​

The .env file contains POKTROLLD_IMAGE_TAG which can be updated based on the images available on poktroll ghcr to update the version of the full_node deployed. As well as the PATH_GATEWAY_IMAGE_TAG which can be updated based on the PATH Gateway images available at path ghcr

B. Creating a Supplier and Deploying a RelayMiner​

A Supplier is an on-chain record that advertises services it'll provide.

A RelayMiner is an operator / service that provides services to offer on the Pocket Network.

Prerequisites for a RelayMiner ​

  • Full Node: This RelayMiner deployment guide assumes the Full Node is deployed in the same docker compose stack; see section (A).
  • A poktroll account with uPOKT tokens: Tokens can be acquired by contacting the team or using the faucet. You are going to need a BIPmnemonic phrase for an existing funded account before continuing below.

Create and fund a Supplier account ​

On the host where you started the full node container, run the commands below to create your account.

Create a new supplier account:

poktrolld keys add supplier-1

Copy the mnemonic that's printed to the screen to the SUPPLIER_MNEMONIC variable in your .env file.

export SUPPLIER_MNEMONIC="foo bar ..."

Save the outputted address to a variable for simplicity::

export SUPPLIER_ADDR="pokt1..."

Make sure to:

source .env

Add funds to your supplier account by either going to the faucet or using the faucet account directly if you have access to it:

poktrolld tx bank send faucet $SUPPLIER_ADDR 10000upokt --chain-id=pocket-beta --yes

You can check that your address is funded correctly by running:

poktrolld query bank balances $SUPPLIER_ADDR

Note: You must wait until full-node has synced up to the current block # before this command and the stake command below (poktrolld tx supplier stake-supplier...) will work successfully. Watch your node's block height here.

If you're waiting to see if your transaction has been included in a block, you can run:

poktrolld query tx --type=hash <hash>

Configure and stake your Supplier ​

Supplier staking config

dev.poktroll.com/operate/configs/supplier_staking_config explains what supplier staking config is and how it can be used.

Verify that the account you're planning to use for SUPPLIER (created above) is available in your local Keyring:

poktrolld keys list --list-names | grep "supplier-1"

Update the provided example supplier stake config:

sed -i -e s/YOUR_NODE_IP_OR_HOST/$NODE_HOSTNAME/g ./stake_configs/supplier_stake_config_example.yaml
sed -i -e s/YOUR_OWNER_ADDRESS/$SUPPLIER_ADDR/g ./stake_configs/supplier_stake_config_example.yaml

Use the configuration to stake your supplier:

poktrolld tx supplier stake-supplier \
  --config=/poktroll/stake_configs/supplier_stake_config_example.yaml \
  --from=supplier-1 \
  --gas=auto \
  --gas-prices=1upokt \
  --gas-adjustment=1.5 \
  --chain-id=pocket-beta \
  --yes

Verify your supplier is staked:

poktrolld query supplier show-supplier $SUPPLIER_ADDR

Configure and run your RelayMiner ​

RelayMiner operation config

dev.poktroll.com/operate/configs/relayminer_config explains what the RelayMiner operation config is and how it can be used.

Update the provided example RelayMiner operation config:

sudo sed -i -e s/YOUR_NODE_IP_OR_HOST/$NODE_HOSTNAME/g relayminer/config/relayminer_config.yaml

Update the backend_url in relayminer_config.yaml with a valid F00C (i.e. ETH MainNet) service URL. We suggest using your own node, but you can get one from Grove for testing purposes.

sudo sed -i 's|backend_url: ".*"|backend_url: "https://eth-mainnet.rpc.grove.city/v1/<APP_ID>"|g' relayminer/config/relayminer_config.yaml

Start up the RelayMiner:

docker compose up -d relayminer

Check logs and confirm the node works as expected:

docker compose logs -f --tail 100 relayminer

C. Creating an Application, a Gateway and Deploying a PATH Gateway​

Create and fund your Application ​

On the host where you started the full node container, run the commands below to create your account.

Create a new application account:

poktrolld keys add application-1

Copy the outputted address to the APPLICATION_ADDR variable in your .env file:

Copy the private key to the APPLICATION_PRIV_KEY_HEX variable in your .env file which can be obtained by running:

export_priv_key_hex application-1

Make sure to:

  source .env

Add funds to your application account by either going to the faucet or using the faucet account directly if you have access to it:

poktrolld tx bank send faucet $APPLICATION_ADDR 10000upokt --chain-id=pocket-beta --yes

You can check that your address is funded correctly by running:

poktrolld query bank balances $APPLICATION_ADDR

Configure and stake your Application ​

Application staking config

dev.poktroll.com/operate/configs/application_staking_config explains what application staking config is and how it can be used.

Verify that the account you're planning to use for APPLICATION (created above) is available in your local Keyring:

poktrolld keys list --list-names | grep "application-1"

Use the configuration to stake your application:

poktrolld tx application stake-application \
  --config=/poktroll/stake_configs/application_stake_config_example.yaml \
  --from=application-1 \
  --gas=auto \
  --gas-prices=1upokt \
  --gas-adjustment=1.5 \
  --chain-id=pocket-beta \
  --yes

Verify your application is staked

poktrolld query application show-application $APPLICATION_ADDR

Create and fund your Gateway ​

On the host where you started the full node container, run the commands below to create your account.

Create a new gateway account:

poktrolld keys add gateway-1

Copy the outputted address to the GATEWAY_ADDR variable in your .env file:

Copy the private key to the GATEWAY_PRIV_KEY_HEX variable in your .env file which can be obtained by running:

export_priv_key_hex gateway-1

Make sure to:

  source .env

Add funds to your gateway account by either going to the faucet or using the faucet account directly if you have access to it:

poktrolld tx bank send faucet $GATEWAY_ADDR 10000upokt --chain-id=pocket-beta --yes

You can check that your address is funded correctly by running:

poktrolld query bank balances $GATEWAY_ADDR

Configure and stake your Gateway ​

Gateway staking config

dev.poktroll.com/operate/configs/gateway_staking_config explains what gateway staking config is and how it can be used.

Verify that the account you're planning to use for GATEWAY (created above) is available in your local Keyring:

poktrolld keys list --list-names | grep "gateway-1"

Use the configuration to stake your gateway:

poktrolld tx gateway stake-gateway \
  --config=/poktroll/stake_configs/gateway_stake_config_example.yaml \
  --from=gateway-1 \
  --gas=auto \
  --gas-prices=1upokt \
  --gas-adjustment=1.5 \
  --chain-id=pocket-beta \
  --yes

Verify your gateway is staked

poktrolld query gateway show-gateway $GATEWAY_ADDR

Delegate your Application to the Gateway ​

poktrolld tx application delegate-to-gateway $GATEWAY_ADDR \
  --from=application-1 \
  --gas=auto \
  --gas-prices=1upokt \
  --gas-adjustment=1.5 \
  --chain-id=pocket-beta \
  --yes

Configure and run your PATH Gateway ​

PATH Gateway allows to use services provided by other operators on Pocket Network.

PATH Gateway operation config

path.grove.city/operate explains what the PATH Gateway operation config is and how it can be used.

Update the provided example PATH Gateway operation config:

sudo sed -i -e s/YOUR_PATH_GATEWAY_ADDRESS/$GATEWAY_ADDR/g gateway/config/gateway_config.yaml
sudo sed -i -e s/YOUR_PATH_GATEWAY_PRIVATE_KEY/$GATEWAY_PRIV_KEY_HEX/g gateway/config/gateway_config.yaml
sudo sed -i -e s/YOUR_OWNED_APP_PRIVATE_KEY/$APPLICATION_PRIV_KEY_HEX/g gateway/config/gateway_config.yaml

Start up the RelayMiner:

docker compose up -d gateway

Check logs and confirm the node works as expected:

docker compose logs -f --tail 100 gateway

Send a relay ​

You can send requests to the newly deployed PATH Gateway. If there are any Suppliers on the network that can provide the service, the request will be routed to them.

The endpoint you want to send request to is: http://service_alias.your_node:path_gateway_port/v1. For example, this is how the request can be routed to ethereum represented by the alias eth:

warning

PATH uses subdomains to route requests to the correct service, which means you need to have a domain name that resolves to the IP address of your node.

curl http://eth.localhost:3000/v1 \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'

You should expect a result that looks like so:

{"jsonrpc":"2.0","id":1,"result":"0x1289571"}

Ensure you get a response ​

To ensure you get a response, you may need to run the request a few times:

for i in {1..10}; do
  curl http://eth.localhost:3000/v1 \
    -X POST \
    -H "Content-Type: application/json" \
    --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' \
    --max-time 1
  echo ""
done

Why?

  • Suppliers may have been staked, but the RelayMiner is no longer running.
  • Pocket does not currently have on-chain quality-of-service
  • Pocket does not currently have supplier jailing