This guide shows how to deploy a LocalNet using pocket-operator.
- TLDR
- 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.
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 clusterMake sure your Kubernetes context is pointed to new kind cluster:
kubectl config current-contextshould return kind-kind. Now you can start LocalNet!
make localnet_upThis 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
spacein 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_downThe 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_shellOpen 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_debugYou 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:
420043b854e78f2d5f03895bba9ef16972913320is a validator #420.66603bc4082281b7de23001ffd237da62c66a839is a fisherperson #666.0010297b55fc9278e4be4f1bcfe52bf9bd0443f8is a servicer #001.314019dbb7faf8390c1f0cf4976ef1215c90b7e4is an application #314.
Currently, we provide a config file that is shared between all validators and a pocket client. We make use of pocket client feature that allows us to override configuration via environment variables. You can check a validator template as a reference.
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_downmake 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
└── templates # Templates for Kubernetes manifests that are consumed by `tilt`
├── v1-validator-template.sh # Shell script that generates Kubenetes manifests for validators, consumed by `tilt`
└── v1-validator-template.yaml.tpl # Template for a single validator, consumed by `v1-validator-template.sh`