From a761c20890a418f8b485b144aec528ab322688d7 Mon Sep 17 00:00:00 2001 From: Nicolas Ochem Date: Tue, 14 Jun 2022 10:51:52 -0700 Subject: [PATCH] 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 --- README.md | 86 +++++++++++++++++++++ charts/tezos/values.yaml | 4 +- docs/04-other-helm-charts.md | 10 +-- docs/Prerequisites.md | 16 +++- docs/{Private_Chain.md => Private-Chain.md} | 10 +-- docs/{Private-Node.md => Public-Node.md} | 4 +- docs/README.md | 3 +- docs/RPC-Auth.md | 5 ++ docs/Tezos-RPC-Service.md | 41 ---------- docs/index.md | 2 + docs/sidebars.js | 8 +- docs/values_to_doc.sh | 11 +-- 12 files changed, 132 insertions(+), 68 deletions(-) rename docs/{Private_Chain.md => Private-Chain.md} (96%) rename docs/{Private-Node.md => Public-Node.md} (95%) create mode 100644 docs/RPC-Auth.md delete mode 100644 docs/Tezos-RPC-Service.md mode change 100644 => 100755 docs/values_to_doc.sh diff --git a/README.md b/README.md index 7df2d829c..81aa506e9 100644 --- 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 index ddd36eb6b..08f5d0965 100644 --- 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 index 0b140c71b..198eea651 100644 --- 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 index 1f44b5e82..ed7b7e634 100644 --- 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 b/docs/Private-Chain.md similarity index 96% rename from docs/Private_Chain.md rename to docs/Private-Chain.md index c8e598f53..34a23d2d2 100644 --- a/docs/Private_Chain.md +++ b/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 b/docs/Public-Node.md similarity index 95% rename from docs/Private-Node.md rename to docs/Public-Node.md index ee39afba4..d66a4794a 100644 --- a/docs/Private-Node.md +++ b/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 index 64d41e72f..0b9dd8ec5 100644 --- 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 new file mode 100644 index 000000000..ce8d359f5 --- /dev/null +++ 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 deleted file mode 100644 index 35a135592..000000000 --- a/docs/Tezos-RPC-Service.md +++ /dev/null @@ -1,41 +0,0 @@ -## 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`. - -# Using a custom Tezos build - -Create a clone of the `[tezos](https://gitlab.com/tezos/tezos)` -repository. [Set up your development environment as usual](https://tezos.gitlab.io/introduction/howtoget.html#setting-up-the-development-environment-from-scratch). Then run: - -```shell -eval $(minikube docker-env) -make docker-image -``` - -This will create a docker image called `tezos:latest` and install it -into the minikube environment. - -Or, if you prefer, you can build the image using: -```shell -./scripts/create_docker_image.sh -``` - -This will create an image with a name like `tezos/tezos:v13-rc1`. -Then you install it thus: -```shell -docker image save | ( eval $(minikube docker-env); docker image load ) -``` - -Either way, inside `$CHAIN_NAME_values.yaml`, change the `images` section to: - -```yaml -images: - octez: -``` - -where image is `tezos:latest` or whatever. - -Then install the chart as above. - diff --git a/docs/index.md b/docs/index.md index 9ac35a9e6..10deb4298 100644 --- 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 index 930ab1e76..eb86b8a5f 100644 --- 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 old mode 100644 new mode 100755 index 9a981071d..3ca8362da --- 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