Skip to content

Commit

Permalink
Mkchain readme updates (#174)
Browse files Browse the repository at this point in the history 
* mkchain doc updates plus some other small doc updates

* Add table of contents in each README

* Clearer text regarding disk size

* Update readme as per PR review comments
  • Loading branch information
@harryttd
harryttd authored Mar 26, 2021
1 parent 7122024 commit 7e53c1b
Show file tree
Hide file tree
Showing 4 changed files with 108 additions and 68 deletions.
13 changes: 11 additions & 2 deletions DEVELOPMENT.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
- [Prerequisites](#prerequisites)
- [Using devspace](#using-devspace)
- [Notes](#notes)
- [Helm Charts](#helm-charts)
- [Creating Charts](#creating-charts)
- [Notes](#notes-1)
- [Creating Docker Images](#creating-docker-images)
- [Releases](#releases)

# Helm Chart Development

## Prerequisites
Expand Down Expand Up @@ -32,7 +41,7 @@

- Run `devspace dev --var CHAIN_NAME=$CHAIN_NAME` (you can leave out the `--var` flag if you used `export CHAIN_NAME=my-chain`).

- You may add the `rpc-auth` devspace [profile](https://devspace.sh/cli/docs/configuration/profiles/basics) by using the `-p rpc-auth` flag in the `devspace dev` command. This tells devspace deploy `rpc-auth` and to redeploy it if its files change. You can also pass another `--var` flag for `rpc-auth` like so: `--var FLASK_ENV=<development|production>`. Devpsace defaults it to `development`. Running with `development` will allow the the python server to hot reload on file changes. Devspace does not need to restart the pod on file changes as the python server file is [synced](https://devspace.sh/cli/docs/configuration/development/file-synchronization) to the container.
- You may add the `rpc-auth` devspace [profile](https://devspace.sh/cli/docs/configuration/profiles/basics) by using the `-p rpc-auth` flag in the `devspace dev` command. This tells devspace deploy `rpc-auth` and to redeploy it if its files change. You can also pass another `--var` flag for `rpc-auth` like so: `--var FLASK_ENV=<development|production>`. Devpsace defaults it to `development`. Running with `development` will allow the python server to hot reload on file changes. Devspace does not need to restart the pod on file changes as the python server file is [synced](https://devspace.sh/cli/docs/configuration/development/file-synchronization) to the container.

Devspace will now do a few things:

Expand Down Expand Up @@ -74,7 +83,7 @@ If you use `helm install|upgrade` (instead of devspace) for local charts, make s

# Creating Docker Images

Currently, we are placing all docker images in the the root level directory. The name of the folder is treated as the name of the image being created.
Currently, we are placing all docker images in the root level directory. The name of the folder is treated as the name of the image being created.

Here is an example of the flow for creating new images and how they are published to Docker Hub via the CI:

Expand Down
128 changes: 72 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,26 @@
- [Prerequisites](#prerequisites)
- [Installing prerequisites](#installing-prerequisites)
- [Mac](#mac)
- [Arch Linux](#arch-linux)
- [Other Operating Systems](#other-operating-systems)
- [Configuring Minikube](#configuring-minikube)
- [Mac](#mac-1)
- [Other Operating Systems](#other-operating-systems-1)
- [Starting Minikube](#starting-minikube)
- [Tezos k8s Helm Chart](#tezos-k8s-helm-chart)
- [Joining Mainnet](#joining-mainnet)
- [Spinning Up a Regular Peer Node](#spinning-up-a-regular-peer-node)
- [Creating a Private Blockchain](#creating-a-private-blockchain)
- [Zerotier](#zerotier)
- [mkchain](#mkchain)
- [Start your private chain](#start-your-private-chain)
- [Adding nodes within the cluster](#adding-nodes-within-the-cluster)
- [Adding external nodes to the cluster](#adding-external-nodes-to-the-cluster)
- [On the computer of the joining node](#on-the-computer-of-the-joining-node)
- [RPC Authentication](#rpc-authentication)
- [Notes](#notes)
- [Development](#development)

# Tezos k8s

This README walks you through:
Expand Down Expand Up @@ -107,17 +130,31 @@ helm repo add tqtezos https://tqtezos.github.io/tezos-helm-charts

# Joining Mainnet

## Spinning Up a Regular Peer Node

Connecting to a public net is easy!

Run:
(See [here](https://tezos.gitlab.io/user/history_modes.html) for info on snapshots and node history modes)

If you'd like to spin up a node that runs with history mode rolling, all you need to do is run:

```shell
helm install tezos-mainnet tqtezos/tezos-chain \
--namespace tqtezos --create-namespace
```

- This creates a Helm [release](https://helm.sh/docs/intro/using_helm/#three-big-concepts) named tezos-mainnet in your k8s cluster.
- k8s will spin up one regular (i.e. non-baking node) which will download and import a mainnet [rolling snapshot](https://tezos.gitlab.io/user/history_modes.html). This will take a few minutes.
If you'd like to spin up a node with history mode full, run:

```shell
helm install tezos-mainnet tqtezos/tezos-chain \
--namespace tqtezos --create-namespace \
--set nodes.regular.tezos-node-0.config.shell.history_mode=full
```

Running either of these commands results in:

- Creating a Helm [release](https://helm.sh/docs/intro/using_helm/#three-big-concepts) named tezos-mainnet in your k8s cluster.
- k8s will spin up one regular (i.e. non-baking node) which will download and import a mainnet snapshot. This will take a few minutes.
- Once the snapshot step is done, your node will be bootstrapped and syncing with mainnet!

You can find your node in the tqtezos namespace with some status information using `kubectl`.
Expand All @@ -138,63 +175,31 @@ You can view logs for your node using the following command:
kubectl -n tqtezos logs -l appType=tezos -c tezos-node -f --prefix
```

## Spinning Up a Baker

In the previous sections you spun one mainnet regular peer node. Here is how you add an additional mainnet baker node.

- Create a yaml file named `baker.yaml`.
- In this file you should copy and paste the yaml below.

```yaml
accounts:
tqtezos_baker_0:
key: edsk...
type: secret

nodes:
baking:
tezos-baking-node-0:
bake_using_account: tqtezos_baker_0
config:
shell:
history_mode: rolling
```
- Notice the `accounts.tqezos_baker_0.key` field above. You should replace that value with your own secret key you want to bake with. The key should begin with prefix `edsk`.
- If you'd like, in the `nodes` section of the yaml, you can replace the `history_mode` with either `archive` or `full`. If you use `full`, a `full` snapshot will be downloaded and imported to the node.
IMPORTANT:

- Run:
- Although spinning up a mainnet baker is possible, we do not recommend running a mainnet baker at this point in time. Secret keys should be handled via an HSM that should remain online, and the keys should be passed through a k8s secret to k8s. This functionality still needs to be implemented.
- You should be aware of `minikube` VM's allocated memory. Especially if you use `minikube` for other applications. It may run out of virtual memory say due to having large docker images. Being that snapshots are relatively large and increasing in size as the blockchain grows, when downloading one, you can potentially run out of disk space. The snapshot is deleted after import. According to `minikube start --help`, default allocated space is 20000mb. You can modify this via the `--disk-size` flag. To view the memory usage of the VM, you can ssh into `minikube`.

```shell
helm upgrade tezos-mainnet tqtezos/tezos-chain \
--namespace tqtezos \
--values <LOCATION OF baker.yaml>
❯ minikube ssh
_ _
_ _ ( ) ( )
___ ___ (_) ___ (_)| |/') _ _ | |_ __
/' _ ` _ `\| |/' _ `\| || , < ( ) ( )| '_`\ /'__`\
| ( ) ( ) || || ( ) || || |\`\ | (_) || |_) )( ___/
(_) (_) (_)(_)(_) (_)(_)(_) (_)`\___/'(_,__/'`\____)
$ df -h
Filesystem Size Used Avail Use% Mounted on
tmpfs 5.2G 593M 4.6G 12% /
devtmpfs 2.8G 0 2.8G 0% /dev
tmpfs 2.9G 0 2.9G 0% /dev/shm
tmpfs 2.9G 50M 2.8G 2% /run
tmpfs 2.9G 0 2.9G 0% /sys/fs/cgroup
tmpfs 2.9G 8.0K 2.9G 1% /tmp
/dev/vda1 17G 12G 4.2G 74% /mnt/vda1
```
After the snapshot has been downloaded and imported you should have a baker up and running that is syncing with mainnet! Run the the `kubectl` commands mentioned in the above section to view status and logs of your node.

IMPORTANT: Especially if you use `minikube` for other applications or have a lot of docker images, you should be aware of `minikube's` virtual machine's allocated memory. Being that snapshots are relatively large and increasing in size as the blockchain grows, you can potentially run out of disk space. According to `minikube start --help`, default allocated space is 20000mb. You can modify this via the `--disk-size` flag. To view the memory usage of the VM, you can ssh into `minikube`.

```shell
❯ minikube ssh
_ _
_ _ ( ) ( )
___ ___ (_) ___ (_)| |/') _ _ | |_ __
/' _ ` _ `\| |/' _ `\| || , < ( ) ( )| '_`\ /'__`\
| ( ) ( ) || || ( ) || || |\`\ | (_) || |_) )( ___/
(_) (_) (_)(_)(_) (_)(_)(_) (_)`\___/'(_,__/'`\____)

$ df -h
Filesystem Size Used Avail Use% Mounted on
tmpfs 5.2G 593M 4.6G 12% /
devtmpfs 2.8G 0 2.8G 0% /dev
tmpfs 2.9G 0 2.9G 0% /dev/shm
tmpfs 2.9G 50M 2.8G 2% /run
tmpfs 2.9G 0 2.9G 0% /sys/fs/cgroup
tmpfs 2.9G 8.0K 2.9G 1% /tmp
/dev/vda1 17G 12G 4.2G 74% /mnt/vda1
```

# Creating a Private Blockchain
## Zerotier
Expand Down Expand Up @@ -241,11 +246,22 @@ export PYTHONUNBUFFERED=x
## Start your private chain
Run the following commands to create the Helm values, and create a Helm release that will start your chain.
Run `mkchain` to create your Helm values
```shell
mkchain $CHAIN_NAME --zerotier-network $ZT_NET --zerotier-token $ZT_TOKEN
```
This will create two files:
1. `./${CHAIN_NAME}_values.yaml`
2. `./${CHAIN_NAME}_invite_values.yaml`
The former is what you will use to create your chain, and the latter is for invitees to join your chain.
Create a Helm release that will start your chain:
```shell
helm install $CHAIN_NAME tqtezos/tezos-chain \
--values ./${CHAIN_NAME}_values.yaml \
--namespace tqtezos --create-namespace
Expand Down
30 changes: 20 additions & 10 deletions mkchain/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
- [Install mkchain](#install-mkchain)
- [Generate Helm Values](#generate-helm-values)
- [mkchain parameters](#mkchain-parameters)
- [Create Tezos Chain](#create-tezos-chain)

# mkchain

Helper program to generate values for the Tezos chain Helm chart
Expand Down Expand Up @@ -43,7 +48,9 @@ To generate these values run:
mkchain $CHAIN_NAME
```

This command will create two yaml files in your current working directory. `<$CHAIN_NAME>_values.yaml` and `<$CHAIN_NAME>_invite_values.yaml`.
This command will create a yaml file in your current working directory: `<$CHAIN_NAME>_values.yaml`

If you configure your chain to run over a Zerotier VPN, mkchain will create an additional file for invitees to join your network: `<$CHAIN_NAME>_invite_values.yaml`.

### mkchain parameters

Expand All @@ -53,15 +60,18 @@ You can explicitly specify some values by:
- directly modifying the values yaml file generated by `mkchain`
- passing arguments to [helm install](https://helm.sh/docs/helm/helm_install/) or [helm upgrade](https://helm.sh/docs/helm/helm_upgrade/) commands using the `--set` flag, which will selectively override the current yaml values

| YAML Key | mkchain argument | Description | Default |
| -------------------------------- | ------------------ | --------------------------------------------------------------------------- | ---------------------- |
| bootstrap_peer | --bootstrap-peer | Peer ip to connect to | |
| images.tezos | --docker-image | Version of the Tezos docker image | tezos/tezos:v8-release |
| number_of_nodes | --number-of-nodes | Number of non-baking nodes in the cluster | 1 |
| number_of_bakers | --number-of-bakers | Number of baking nodes in the cluster | 1 |
| rpc_auth | --rpc-auth | Whether or not an [RPC auth](../rpc-auth/README.md) backend will be spun up | False |
| zerotier_config.zerotier_network | --zerotier-network | Zerotier network id for external chain access | |
| zerotier_config.zerotier_token | --zerotier-token | Zerotier token for external chain access | |
| YAML Key | mkchain argument | Description | Default |
| -------------------------------- | ------------------------ | --------------------------------------------------------------------------- | ---------------------- |
| | -h | mkchain help message | |
| | -v | mkchain version | |
| | --number-of-bakers | Number of baking nodes in the cluster | 1 |
| | --number-of-nodes | Number of non-baking nodes in the cluster | 0 |
| bootstrap_peers | --bootstrap-peers | Peer ips to connect to | [] |
| expected_proof_of_work | --expected-proof-of-work | Node identity generation difficulty | 0 |
| images.tezos | --tezos-docker-image | Version of the Tezos docker image to run | tezos/tezos:v8-release |
| rpc_auth | --rpc-auth | Whether or not an [RPC auth](../rpc-auth/README.md) backend will be spun up | False |
| zerotier_config.zerotier_network | --zerotier-network | Zerotier network id for external chain access | |
| zerotier_config.zerotier_token | --zerotier-token | Zerotier token for external chain access | |

## Create Tezos Chain

Expand Down
5 changes: 5 additions & 0 deletions rpc-auth/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
- [Deploy RPC Auth Backend](#deploy-rpc-auth-backend)
- [Client Authentication](#client-authentication)
- [Prerequisites](#prerequisites)
- [Authentication flow](#authentication-flow)

# Tezos RPC Authentication

`rpc-auth` provides a mechanism where a user authenticates themselves and will receive a secret url that they then use to make RPC calls.
Expand Down

0 comments on commit 7e53c1b

Please sign in to comment.