diff --git a/docs/install.md b/docs/install.md index c7ef14c69..1a6101df6 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,26 +1,68 @@ # Installing Warnet -Warnet requires Kubernetes (k8s) and helm in order to run the network. Kubernetes can be run remotely or locally (with minikube or Docker Desktop). `kubectl` and `helm` must be run locally to administer the network. +Warnet runs on Kubernetes (k8s) and requires the Helm Kubernetes package manager in order to run the network. +The Kubernetes cluster can be run locally via minikube, Docker Desktop, k3d or similar, or remotely via Googles GKE, Digital Ocean, etc.. +The utilities `kubectl` and `helm` must be installed and found on $PATH to administer the network. + +## Install Warnet + +Either install warnet via pip, or clone the source and install: + +### via pip + +You can install warnet via `pip` into a virtual environment with + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install warnet +``` + +### via cloned source + +You can install warnet from source into a virtual environment with + +```bash +git clone https://github.com/bitcoin-dev-project/warnet.git +cd warnet +python3 -m venv .venv +source .venv/bin/activate +pip install -e . +``` ## Dependencies -### Remote (cloud) cluster +The [`helm`](https://helm.sh/) and [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) utilities are required for all configurations to talk to and administrate your cluster. +These can be installed using your operating system's package manager, a third party package manager like [homebrew](https://brew.sh/), or as binaries directly into a python virtual environment created for warnet, by following the steps in [Use warnet to install dependencies](#use-warnet-to-install-dependencies). + +If you are using a cloud-based cluster, these are the only tools needed. + +### Use warnet to install dependencies -The only two dependencies of Warnet are `helm` and `kubectl` configured to talk to your cloud cluster. +```bash +# Ensure the virtual environment is active +source .venv/bin/activate + +# Run `warnet setup` to be guided through downloading binaries into the +# python virtual environment +warnet setup +``` ### Running Warnet Locally -If the number of nodes you are running can run on one machine (think a dozen or so) then Warnet can happily run on a local Kubernetes. Two supported k8s implementations are Minikube and K8s as part of Docker Desktop. +If the number of nodes you are running can run on one machine (think a dozen or so) then Warnet can happily run on a local Kubernetes. +Two supported local Kubernetes implementations are Minikube and Docker Desktop. #### Docker Desktop -[Docker desktop](https://www.docker.com/products/docker-desktop/) includes the docker engine itself and has an option to enable Kubernetes. Simply installing it and enabling Kubernetes should be enough. - -[Helm](https://helm.sh/docs/intro/install/) is also required to be installed. +[Docker desktop](https://www.docker.com/products/docker-desktop/) includes the docker engine itself and has an option to enable Kubernetes. +Install it and enable Kubernetes in the option menu to start a cluster. #### Minikube -Minikube requires a backend to run on with the supported backend being Docker. So if installing Minikube, you may need to install docker first. Please see [Installing Docker](https://docs.docker.com/engine/install/) and [Installing Minkube](https://minikube.sigs.k8s.io/docs/start/). +Minikube requires a backend to run on with the supported backend being Docker. + +[Install Docker](https://docs.docker.com/engine/install/) first, and then proceed to [Install Minkube](https://minikube.sigs.k8s.io/docs/start/). After installing Minikube don't forget to start it with: @@ -30,9 +72,10 @@ minikube start Minikube has a [guide](https://kubernetes.io/docs/tutorials/hello-minikube/) on getting started which could be useful to validate that your minikube is running correctly. -### Testing kubectl and helm +## Testing kubectl and helm -The following commands should run on both local and remote clusters. Do not proceed unless kubectl and helm are working. +After installing `kubectl` and `helm` the following commands should run successfully on either a local or remote cluster. +Do not proceed unless `kubectl` and `helm` are working. ```shell helm repo add examples https://helm.github.io/examples @@ -42,41 +85,18 @@ kubectl get pods helm uninstall hello ``` -#### Managing Kubernetes cluster +#### Managing a Kubernetes cluster The use of a k8s cluster management tool is highly recommended. We like to use `k9s`: https://k9scli.io/ -## Install Warnet - -Either install warnet via pip, or clone the source and install: - -### via pip - -You can install warnet via `pip` into a virtual environment with - -```bash -python3 -m venv .venv -source .venv/bin/activate -pip install warnet -``` - -### via cloned source - -You can install warnet from source into a virtual environment with - -```bash -git clone https://github.com/bitcoin-dev-project/warnet.git -cd warnet -python3 -m venv .venv -source .venv/bin/activate -pip install -e . -``` - ## Running To get started first check you have all the necessary requirements: +> [!TIP] +> Don't forget to activate your python virtual environment when using new terminals! + ```bash warnet setup ``` @@ -89,4 +109,4 @@ warnet init # Or in a directory of choice warnet new -``` \ No newline at end of file +```