Docker Compose Walkthrough
- Introduction and Cheat Sheet
- Key Terms in Morse and Shannon
- Understanding Actors in the Shannon upgrade
- Prerequisites
- A. Deploying a Full Node
- B. Creating a Supplier and Deploying a RelayMiner
- C. Creating an Application and Deploying an AppGate Server
- D. Creating a Gateway Deploying an Gateway Server
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
.
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
Morse
Same inMorse
andShannon
. - In
Shannon
- In
Node
- AMorse
actor that stakes to provide Relay services.- In
Morse
- AllValidator
are nodes but only the top 1000 stakesNode
s areValidator
s - This actor is not present in
Shannon
and decoupled intoSupplier
and aRelayMiner
.
- In
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).
- In
RelayMiner
- The off-chain service that provides Relay services on behalf of aSupplier
.- In
Shannon
- This actor is responsible for providing the Relay services.
- In
AppGate Server
- The off-chain service that provides Relay services on behalf of anApplication
orGateway
.
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
introduces the AppGate Server
, a software component that
acts on behalf of either Applications
or Gateways
to access services provided
by Pocket Network Supplier
s 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.
0. Software & Tooling
Ensure the following software is installed on your system:
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
A. Deploying a Full Node
Launch the Node
Note: You may need to replace docker-compose
with docker compose
if you are
running a newer version of Docker where docker-compose
is integrated into docker
itself.
Initiate the node with:
docker-compose up -d poktrolld
Monitor node activity through logs with:
docker-compose logs -f --tail 100 poktrolld
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.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/data/
# 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 ghcr
to update the version of the full_node
deployed.
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.
0. 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, configure 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=poktroll --yes
You can check that your address is funded correctly by running:
poktrolld query bank balances $SUPPLIER_ADDR
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
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
Use the configuration to stake your supplier:
poktrolld tx supplier stake-supplier --config=/poktroll/stake_configs/supplier_stake_config_example.yaml --from=supplier-1 --chain-id=poktroll --yes
If you need to change any of the configurations in your staking config, you MUST
increase the stake by at least one uPOKT. This is the stake_amount
field
in the supplier_stake_config_example.yaml
file above.
Verify your supplier is staked:
poktrolld query supplier show-supplier $SUPPLIER_ADDR
Configure and run your RelayMiner
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:
sed -i -e s/YOUR_NODE_IP_OR_HOST/$NODE_HOSTNAME/g relayminer-example/config/relayminer_config.yaml
Update the backend_url
in relayminer_config.yaml
with a valid `002(i.e. ETH MainNet)
service URL. We suggest using your own node, but you can get one from Grove for testing purposes.
sed -i "s|backend_url:\".*\"|backend_url: \"https://eth-mainnet.rpc.grove.city/v1/<APP_ID>\"|g" relayminer-example/config/relayminer_config.yaml
Start up the RelayMiner:
docker-compose up -d relayminer-example
Check logs and confirm the node works as expected:
docker-compose logs -f --tail 100 relayminer-example
C. Creating an Application and Deploying an AppGate Server
AppGate Server allows to use services provided by other operators on Pocket Network.
0. Prerequisites for an AppGate Server
- Full Node: This AppGate Server 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. You are going to need a BIPmnemonic phrase for an existing funded account.
Create, configure 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 mnemonic that's printed to the screen to the APPLICATION_MNEMONIC
variable in your .env
file.
export APPLICATION_MNEMONIC="foo bar ..."
Save the outputted address to a variable for simplicity::
export APPLICATION_ADDR="pokt1..."
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=poktroll --yes
You can check that your address is funded correctly by running:
poktrolld query bank balances $APPLICATION_ADDR
Configure and stake your Application
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 --chain-id=poktroll --yes
Verify your application is staked
poktrolld query application show-application $APPLICATION_ADDR
Configure and run your AppGate Server
dev.poktroll.com/operate/configs/appgate_server_config explains what the AppGate Server operation config is and how it can be used.
appgate-server-example/config/appgate_config.yaml
docker-compose up -d appgate-server-example
Check logs and confirm the node works as expected:
docker-compose logs -f --tail 100 appgate-server-example
Send a relay
You can send requests to the newly deployed AppGate Server. 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://your_node:appgate_server_port/service_id
. For example, this is how the request can be routed to ethereum
represented by 0021
:
curl http://$NODE_HOSTNAME:85/0021 \
-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"}
D. Creating a Gateway Deploying an Gateway Server
Gateway Server allows to use services provided by other operators on Pocket Network.
0. Prerequisites for a Gateway Server
- Full Node: This Gateway Server 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. You are going to need a BIPmnemonic phrase for an existing funded account.
Create, configure 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 mnemonic that's printed to the screen to the GATEWAY_MNEMONIC
variable in your .env
file.
export GATEWAY_MNEMONIC="foo bar ..."
Save the outputted address to a variable for simplicity::
export GATEWAY_ADDR="pokt1..."
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=poktroll --yes
You can check that your address is funded correctly by running:
poktrolld query bank balances $GATEWAY_ADDR
Configure and stake your Gateway
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 --chain-id=poktroll --yes
Verify your gateway is staked
poktrolld query gateway show-gateway $GATEWAY_ADDR
Configure and run your Gateway Server
dev.poktroll.com/operate/configs/appgate_server_config explains what the Gateway Server operation config is and how it can be used.
appgate-server-example/config/gateway_config.yaml
docker-compose up -d gateway-example
Check logs and confirm the node works as expected:
docker-compose logs -f --tail 100 gateway-example
Delegate your Application to the Gateway
poktrolld tx application delegate-to-gateway $GATEWAY_ADDR --from=application-1 --chain-id=poktroll --chain-id=poktroll --yes
[BONUS] Deploy a PATH Gateway
If you want to deploy a real Gateway, you can use Grove's PATH.
Send a relay
You can send requests to the newly deployed Gateway Server. 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://your_node:gateway_server_port/service_id
. For example, this is how the request can be routed to ethereum
represented by 0021
:
curl http://$NODE_HOSTNAME:84/0021?applicationAddr=$APPLICATION_ADDR \
-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"}
5.1 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://$NODE_HOSTNAME:85/0021 \
-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
- You can follow along with buildwithgrove/path for what we'll open source.