This guide shows how to deploy a LocalNet using pocket-operator.
- TL;DR
- Dependencies
- LocalNet
- How to change configuration files
- How does it work?
- Troubleshooting
- Code Structure
If you feel adventurous, and you know what you're doing, here is a rapid guide to start LocalNet:
- Install Docker
- Install Kind (e.g.,
brew install kind
) - Create Kind cluster (e.g.,
kind create cluster
) - Start LocalNet (e.g.,
make localnet_up
)
Otherwise, please continue with the full guide.
All necessary dependencies, except Docker and Kubernetes cluster, are installed automatically when running make install_cli_deps
. The following dependencies are required for LocalNet to function:
- tilt
- Docker or Docker Desktop
Kubernetes cluster
: refer to Choosing Kubernetes Distribution section for more details.kubectl
: CLI is required and should be configured to access the cluster. This should happen automatically if using Docker Desktop, Rancher Desktop, k3s, k3d, minikube, etc.- helm: required to template the YAML manifests for the dependencies (e.g., Postgres, Grafana). Installation instructions available.
- rsync: required to for some extensions used with
Tilt
; https://github.com/tilt-dev/tilt-extensions/tree/master/syncback#usage
While any Kubernetes distribution should work, we've had success and recommend to use Kind. To run Kind Kubernetes clusters, you need to have Docker installed.
Kind depends solely on Docker. To install Kind, follow this page.
Create a new cluster:
kind create cluster
Make sure your Kubernetes context is pointed to new kind cluster:
kubectl config current-context
should return kind-kind
. Now you can start LocalNet!
make localnet_up
This action will create a file called localnet_config.yaml
in the root of the repo if it doesn't exist. The default configuration can be found in Tiltfile.
The developer can then view logs either from a browser or terminal.
make localnet_logs_validators
- shows prior logsmake localnet_logs_validators_follow
- shows prior logs and follows the new log lines as validators do their work
- Pressing
space
in terminal where you startedtilt
- Go to localhost:10350
When starting a k8s LocalNet, localnet_config.yaml
is generated (with default configs) in the root of the repo if doesn't already exist.
The config file can be modified to scale the number of actors up/down. As long as localnet_up
is running, the changes should be automatically applied within seconds.
demo-scaling.mp4
make localnet_down
The command stops LocalNet and cleans up all the resources, including the postgres database.
As the workloads run in Kubernetes, you can see and modify any resources on your local kubernetes by a tool of your choice (k9s, Lens, VSCode extension, etc), but note that Tilt will change manifests back eventually.
Open a shell in the pod that has client
cli available. It gets updated automatically whenever the code changes:
make localnet_shell
Open a client debug
cli. It allows to interact with blockchain, e.g. change pace maker mode, reset to genesis, etc. It gets updated automatically whenever the code changes (though you would need to stop/start the binary to execute the new code):
make localnet_client_debug
You can find private keys and addresses for all actors in the private-keys.yaml file. They have been pre-generated and follow a specific pattern – they start with pre-determined numbers for easier troubleshooting and debugging.
Addresses begin with YYYXX
number, where YYY
is a number of an actor and XX
is a type of actor.
The current mapping for XX
is:
01
- Application02
- Servicer03
- Fisherman04
- Validator
For example:
420043b854e78f2d5f03895bba9ef16972913320
is a validator #420.66603bc4082281b7de23001ffd237da62c66a839
is a fisherperson #666.0010297b55fc9278e4be4f1bcfe52bf9bd0443f8
is a servicer #001.314019dbb7faf8390c1f0cf4976ef1215c90b7e4
is an application #314.
Applications with the following addresses are staked on LocalNet, through the applications field of the genesis.json in the LocalNet configuration
00001fff518b1cdddd74c197d76ba5b5dedc0301
00101f2ff54811e84df2d767c661f57a06349b7e
These addresses can be used for e.g. testing the CLI.
Servicers with the following addresses are staked on LocalNet, through the servicers field of the genesis.json in the LocalNet configuration
00002b8cea1bcc3dadc72ebecf95564ceb9c2e2a
001022b138896c4c5466ac86b24a9bbe249905c2
Configurations can be changed in helm charts where network protocol actor configs are maintained. You can find them in this directory.
config.json
file is created using the config
section content in values.yaml
. For example, you can find the configuration for a validator here.
If you need to add a new parameter – feel free to modify the section in place. Some of the parameters that contain secrets (e.g. private key), are stored in Secrets object and injected as environment variables.
Please refer to helm charts documentation for more details.
You may also create a overrides YAML file in the charts/pocket
directory and override the default values for the various actors.
Override files supported:
- pocket-fisherman-overrides.yaml
- pocket-servicer-overrides.yaml
- pocket-validator-overrides.yaml
touch charts/pocket/pocket-validator-overrides.yaml
For example, to enable CORS for the RPC server, you can run the following command. Note, this overrides config.json for all validators in localnet.
cat <<EOF > charts/pocket/pocket-validator-overrides.yaml
config:
rpc:
use_cors: true
EOF
tilt reads the Tiltfile
, where LocalNet configs are specified. Tiltfile
is written in Starlark, a dialect of Python.
The k8s manifests that tilt
submits to the cluster can be found in this directory. Please refer to code structure for more details where different parts are located.
Tilt continuously monitors files on local filesystem in specific directories, and it rebuilds the binary and distributes it to the pods on every code change. This allows developers to iterate on the code and see the changes immediately (i.e. hot-reloading).
Developers might experience issues with running LocalNet on Kubernetes.
Issues might be related to the fact different developers run different clusters/OS/environments.
Machines going to sleep and that might not play well with virtual machines, postgres or pocket client.
Visit the tilt web UI by pressing space
in the shell where you started tilt or by visiting this webpage.
If you see any errors, you can click Trigger Update
on a resource that has issues to restart the service or retry a command.
If force triggering an update didn't work, try the following:
make localnet_down
make localnet_up
If a force restart didn't help, try rebuilding local kubernetes cluster using the tool you're managing your cluster with (e.g. Docker Desktop, Rancher Desktop, k3s, k3d, minikube, etc).
build/localnet
├── README.md # This file
├── Tiltfile # File outlining tilt process
├── dependencies # Helm charts that install all the dependencies needed to run and observe LocalNet
│ ├── Chart.yaml # Main file of the helm chart, contains metadata
│ ├── dashboards # Directory with all the dashboards that are automatically imported to Grafana
│ │ ├── README.md # README file with instructions on how to add a new dashboard
│ │ └── raintree-telemetry-graphs.json # Raintree Telemetry dashboard
│ ├── requirements.yaml # Specifies dependencies of the chart, this allows us to install all the dependencies with a single command
│ ├── templates # Additional Kubernetes manifests that we need to connect different dependencies together
│ │ ├── _helpers.tpl
│ │ ├── dashboards.yml
│ │ └── datasources.yml
│ └── values.yaml # Configuration values that override the default values of the dependencies, this allows us to connect dependencies together and make them available to our LocalNet services
└── manifests # Static YAML Kubernetes manifests that are consumed by `tilt`
├── cli-client.yaml # Pod that has the latest binary of the pocket client. Makefile targets run CLI in this pod.
├── configs.yaml # Location of the config files (default configs for all validators and a genesis file) that are shared across all actors
├── network.yaml # Networking configuration that is shared between different actors, currently a Service that points to all validators
└── private-keys.yaml # Pre-generated private keys with a semantic format for easier development