Docusaurus fixes (#462)

* remove link in wrong place * make values_to_docs executable * put prerequisites in front, make some prerequs optional * rpc auth rename + fixes * make values_to_doc work on mac os * make script work on mac os - replace head with sed * better docs/README instructions * appType=tezos-node => octez-node * add chart repo to prerequisites * re-add prerequisites (we will transfer all README to docusaurus later) * add link to trd helm chart * add backticks per review * link to all charts in repo * kebab case page names in doc * add a quick start caveat * move IFS= above in the doc generation script * -c tezos-node => octez-node * re-set README as it was before "docusaurus initial" * private node => public node * remove custom tezos builds instructions from rpc auth
oxheadalpha · Jun 14, 2022 · a761c20 · a761c20
1 parent dc8c55a
commit a761c20
Show file tree

Hide file tree

Showing 12 changed files with 132 additions and 68 deletions.
diff --git a/README.md b/README.md
@@ -37,6 +37,92 @@ Follow the prerequisites step first. Then you can jump to either [joining mainne
 
 NOTE: You do not need to clone this repository! All necessary components will be installed.
 
+## Prerequisites
+
+- python3 (>=3.7)
+- [docker](https://docs.docker.com/get-docker/)
+- [kubectl](https://kubernetes.io/docs/reference/kubectl/kubectl/)
+- [minikube](https://minikube.sigs.k8s.io/docs/)
+- [helm](https://helm.sh/)
+- A [ZeroTier](https://www.zerotier.com/) network with api access token
+
+## Installing prerequisites
+
+This section varies depending on OS.
+
+### Mac
+
+- Install [Docker Desktop](https://docs.docker.com/docker-for-mac/install/).
+
+- Start Docker Desktop and follow the setup instructions. Note: You may quit Docker after it has finished setting up. It is not required that Docker Desktop is running for you to run a Tezos chain.
+
+- Install [homebrew](https://brew.sh/):
+
+  ```shell
+  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+  ```
+
+- Install other prerequisites:
+  ```shell
+  brew install python3 kubectl minikube helm
+  ```
+
+### Arch Linux
+
+```shell
+pacman -Syu && pacman -S docker python3 minikube kubectl kubectx helm
+```
+
+### Other Operating Systems
+
+Please see the respective pages for installation instructions:
+
+- [python3](https://www.python.org/downloads/)
+- [docker](https://docs.docker.com/get-docker/)
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+- [minikube](https://minikube.sigs.k8s.io/docs/start/)
+- [helm](https://helm.sh/docs/intro/install/)
+
+## Configuring Minikube
+
+It is suggested to deploy minikube as a virtual machine. This requires a virtual machine [driver](https://minikube.sigs.k8s.io/docs/drivers/).
+
+### Mac
+
+Requires the [hyperkit](https://minikube.sigs.k8s.io/docs/drivers/hyperkit/) driver. This comes already bundled together with Docker Desktop.
+
+Make hyperkit the default minikube driver:
+
+```shell
+minikube config set driver hyperkit
+```
+
+(Note: We do not use Docker itself as the minikube driver due to an [issue](https://github.com/kubernetes/minikube/issues/7332) regarding the minikube ingress addon that is required by [rpc-auth](./rpc-auth/README.md))
+
+### Other Operating Systems
+
+If in the next step minikube does not start correctly, you may need to configure a different driver for it. Please see the minikube docs [here](https://minikube.sigs.k8s.io/docs/drivers/) for more information.
+
+## Starting Minikube
+
+```shell
+minikube start
+```
+
+Configure your shell environment to use minikube’s Docker daemon:
+
+```shell
+eval $(minikube docker-env)
+```
+
+This allows you to run Docker commands inside of minikube. For example: `docker images` to view the images that minikube has.
+
+If you want to unset your shell from using minikube's docker daemon:
+
+```shell
+eval $(minikube docker-env -u)
+```
+
 ## Tezos k8s Helm Chart
 
 To add the Tezos k8s Helm chart to your local Helm chart repo, run:

diff --git a/charts/tezos/values.yaml b/charts/tezos/values.yaml
@@ -39,7 +39,7 @@ accounts: {}
 # `accounts` is a map where keys are account aliases and values are maps of
 # fields `key`, `is_bootstrap_baker_account`, `bootstrap_balance` and `signer_url`.
 #
-# The key field can be set to a public or private key. For a bootstrap baker,
+# The `key` field can be set to a public or private key. For a bootstrap baker,
 # it must be set to a private key. The key type will be recognized automatically,
 # and the pod will fail if the key type is unexpected.
 #
@@ -101,8 +101,6 @@ should_generate_unsafe_deterministic_data: false
 # as a list because their names are simply -N appended to the statefulsetname.
 # Said names are typically kebab case.
 #
-# https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/
-#
 # Params at the statefulset level:
 # - "config": The "config" property should mimic the structure of a node's
 #             config.json. Run `tezos-node config --help` for more info.

diff --git a/docs/04-other-helm-charts.md b/docs/04-other-helm-charts.md
@@ -2,8 +2,8 @@
 
 The Tezos-k8s project also maintains several other helm charts:
 
-* **pyrometer**: a chart to deploy the [Pyrometer Tezos monitoring tool](https://gitlab.com/tezos-kiln/pyrometer)
-* **rpc-auth**: a vending-machine to dispense Tezos RPC access
-* **tezos-faucet**: a faucet to dispense pre-activated accounts (backend only)
-* **snapshotEngine**: an utility to generate Tezos snapshots from running nodes, using Kubernetes CSI driver
-* **tezos-reward-distributor**: a chart to deploy [TRD](https://tezos-reward-distributor-organization.github.io/tezos-reward-distributor/)
+* **[pyrometer](https://github.com/oxheadalpha/tezos-k8s/tree/master/charts/pyrometer)**: a chart to deploy the [Pyrometer Tezos monitoring tool](https://gitlab.com/tezos-kiln/pyrometer)
+* **[rpc-auth](https://github.com/oxheadalpha/tezos-k8s/tree/master/charts/rpc-auth)**: a vending-machine to dispense Tezos RPC access
+* **[tezos-faucet](https://github.com/oxheadalpha/tezos-k8s/tree/master/charts/tezos-faucet)**: a faucet to dispense pre-activated accounts (backend only)
+* **[snapshotEngine](https://github.com/oxheadalpha/tezos-k8s/tree/master/charts/snapshotEngine)**: an utility to generate Tezos snapshots from running nodes, using Kubernetes CSI driver
+* **[tezos-reward-distributor](https://github.com/oxheadalpha/tezos-k8s/tree/master/charts/tezos-reward-distributor)**: a chart to deploy [TRD](https://tezos-reward-distributor-organization.github.io/tezos-reward-distributor/)
diff --git a/docs/Prerequisites.md b/docs/Prerequisites.md
@@ -3,9 +3,16 @@
 - python3 (>=3.7)
 - [docker](https://docs.docker.com/get-docker/)
 - [kubectl](https://kubernetes.io/docs/reference/kubectl/kubectl/)
-- [minikube](https://minikube.sigs.k8s.io/docs/)
 - [helm](https://helm.sh/)
-- A [ZeroTier](https://www.zerotier.com/) network with api access token
+- (optional, for distributed private chains) A [ZeroTier](https://www.zerotier.com/) network with api access token
+
+### For local deployment
+
+- [minikube](https://minikube.sigs.k8s.io/docs/)
+
+### For deployment on a cloud platform (AWS)
+
+- we recommmend [pulumi](https://www.pulumi.com/docs/get-started/install/), an infrastructure-as-code platform, for cloud deployments
 
 ## Installing prerequisites
 
@@ -84,3 +91,8 @@ If you want to unset your shell from using minikube's docker daemon:
 eval $(minikube docker-env -u)
 ```
 
+Add the Oxhead Alpha Helm chart repository to your local Helm installation:
+
+```
+helm repo add oxheadalpha https://oxheadalpha.github.io/tezos-helm-charts/
+```
diff --git a/docs/Private_Chain.md → docs/Private-Chain.md b/docs/Private_Chain.md → docs/Private-Chain.md
@@ -79,13 +79,13 @@ perform the following tasks:
 You can find your node in the oxheadalpha namespace with some status information using kubectl.
 
 ```shell
-kubectl -n oxheadalpha get pods -l appType=tezos-node
+kubectl -n oxheadalpha get pods -l appType=octez-node
 ```
 
 You can view (and follow using the `-f` flag) logs for your node using the following command:
 
 ```shell
-kubectl -n oxheadalpha logs -l appType=tezos-node -c tezos-node -f --prefix
+kubectl -n oxheadalpha logs -l appType=octez-node -c octez-node -f --prefix
 ```
 
 Congratulations! You now have an operational Tezos based permissioned
@@ -179,7 +179,7 @@ helm upgrade $CHAIN_NAME oxheadalpha/tezos-chain \
 
 The nodes will start up and establish peer-to-peer connections in a full mesh topology.
 
-List all of your running nodes: `kubectl -n oxheadalpha get pods -l appType=tezos-node`
+List all of your running nodes: `kubectl -n oxheadalpha get pods -l appType=octez-node`
 
 ## Adding external nodes to the cluster
 
@@ -215,9 +215,9 @@ Congratulations! You now have a multi-node Tezos based permissioned chain.
 On each computer, run this command to check that the nodes have matching heads by comparing their hashes (it may take a minute for the nodes to sync up):
 
 ```shell
-kubectl get pod -n oxheadalpha -l appType=tezos-node -o name |
+kubectl get pod -n oxheadalpha -l appType=octez-node -o name |
 while read line;
-  do kubectl -n oxheadalpha exec $line -c tezos-node -- /usr/local/bin/tezos-client rpc get /chains/main/blocks/head/hash;
+  do kubectl -n oxheadalpha exec $line -c octez-node -- /usr/local/bin/tezos-client rpc get /chains/main/blocks/head/hash;
 done
 ```
 

diff --git a/docs/Private-Node.md → docs/Public-Node.md b/docs/Private-Node.md → docs/Public-Node.md
@@ -19,7 +19,7 @@ Running this results in:
 You can find your node in the oxheadalpha namespace with some status information using `kubectl`.
 
 ```shell
-kubectl -n oxheadalpha get pods -l appType=tezos-node
+kubectl -n oxheadalpha get pods -l appType=octez-node
 ```
 
 You can monitor (and follow using the `-f` flag) the logs of the snapshot downloader/import container:
@@ -31,7 +31,7 @@ kubectl logs -n oxheadalpha statefulset/rolling-node -c snapshot-downloader -f
 You can view logs for your node using the following command:
 
 ```shell
-kubectl -n oxheadalpha logs -l appType=tezos-node -c tezos-node -f --prefix
+kubectl -n oxheadalpha logs -l appType=octez-node -c octez-node -f --prefix
 ```
 
 IMPORTANT:

diff --git a/docs/README.md b/docs/README.md
@@ -15,5 +15,6 @@ To render locally:
 
 ```
 npm install
-./node_modules/.bin/docusaurus serve --build
+npm run build
+npm start
 ```
diff --git a/docs/RPC-Auth.md b/docs/RPC-Auth.md
@@ -0,0 +1,5 @@
+## RPC Authentication
+
+You can optionally spin up an RPC authentication backend allowing trusted users to make RPC requests to your cluster.
+
+Follow the steps at [rpc-auth/README.md](https://github.com/oxheadalpha/tezos-k8s/blob/master/rpc-auth/README.md).
diff --git a/docs/Tezos-RPC-Service.md b/docs/Tezos-RPC-Service.md
diff --git a/docs/index.md b/docs/index.md
@@ -17,6 +17,8 @@ Tezos-k8s is actively maintained by the team at [Oxhead Alpha](https://oxheadalp
 
 ## Quick start
 
+We assume you have access to a Kubernetes cluster and helm installed (see [Prerequisites](Prerequisites)).
+
 To deploy a Tezos mainnet node:
 
 1. Add the Oxhead Alpha Helm chart repository to your local Helm installation:

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -7,21 +7,21 @@ const sidebars = {
   // But you can create a sidebar manually
   tezosK8sSidebar: [
     'index',
+    'Prerequisites',
     {
       type: 'category',
       label: 'Common use cases',
       collapsed: false,
       items: [
-        'Private-Node',
-        'Private_Chain',
-        'Tezos-RPC-Service']
+        'Public-Node',
+        'Private-Chain',
+        'RPC-Auth']
     },
     {
       type: 'category',
       label: 'Tezos-k8s helm chart',
       collapsed: false,
       items: ['helm-chart',
-        'Prerequisites',
         'Tezos-Accounts',
         'Tezos-Nodes',
         'Tezos-Signers',

diff --git a/docs/values_to_doc.sh b/docs/values_to_doc.sh
@@ -2,7 +2,8 @@
 
 extract_markdown() {
   uncommented=false
-  while IFS= read -r line; do
+  IFS=
+  echo "$1" | while read -r line; do
     if [[ $line =~ ^# ]]; then
       if [[ "$uncommented" == "true" ]]; then
          echo '```'
@@ -16,15 +17,15 @@ extract_markdown() {
       uncommented=true
       echo "$line"
     fi
-  done <<< $1
+  done
   if [[ "$uncommented" == "true" ]]; then
      echo '```'
   fi
 }
 
-lines=$(cat ../charts/tezos/values.yaml  | awk '/# Nodes/,/End nodes/' | head -n -1)
+lines=$(cat ../charts/tezos/values.yaml  | awk '/# Nodes/,/End nodes/' | sed '$d' )
 extract_markdown "$lines"  > 01-Tezos-Nodes.md
-lines=$(cat ../charts/tezos/values.yaml  | awk '/# Accounts/,/End Accounts/' | head -n -1)
+lines=$(cat ../charts/tezos/values.yaml  | awk '/# Accounts/,/End Accounts/' | sed '$d' )
 extract_markdown "$lines"  > 02-Tezos-Accounts.md
-lines=$(cat ../charts/tezos/values.yaml  | awk '/# Signers/,/End Signers/' | head -n -1)
+lines=$(cat ../charts/tezos/values.yaml  | awk '/# Signers/,/End Signers/' | sed '$d' )
 extract_markdown "$lines"  > 03-Tezos-Signers.md