feat: updated documentation based on feedback (#192)

* marked local setup optional. Added mermaid diagram * Added consume tutorial * Minor edits * Simplified docs * De-duplicated teamspaces instructions * Lots of updates * Added UI
c6o · Apr 12, 2024 · 82bbc1e · 82bbc1e
1 parent 44ce3a2
commit 82bbc1e
Show file tree

Hide file tree

Showing 25 changed files with 676 additions and 569 deletions.
diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md
@@ -4,46 +4,12 @@ sidebar_position: 1
 
 # Getting Started
 
-Sign up or log in to the [Codezero Hub](https://hub.codezero.io).
-The onboarding wizard will guide you through creating an organization and your first Teamspace.
+These are the general steps for setting up a Teamspace. Apart from setting up a new Kubernetes cluster, the following steps should take less than 10 minutes to complete. These steps should be carried out by someone who is comfortable around Kubernetes:
 
-## Install Codezero in your Cluster
+1. Identify an existing Kubernetes cluster or create a new Kubernetes cluster
+1. Create a Codezero account and Organization on the Codezero Hub
+1. Register a Teamspace name that is unique to the Organization
+1. Install the Codezero System on the Kubernetes cluster in order to Certify it as a Teamspace
+1. Invite team members to the Organization
 
-After creating your Teamspace you need to install the Codezero Space Agent. Click on Helm Install to copy the Helm install string. This install command is unique to your cluster. It includes a one-time token that is used to certify the Teamspace.
-
-![Install Codezero](./_media/ts-helm.jpg)
-
-## Wait for Certification
-
-Finally, you should see the Certification column change to Certified and shortly thereafter, you should see an IP address or Host Name show up under DNS. At this time, your Teamspace is ready for use.
-
-![Install Codezero](./_media/ts-certified.jpg)
-
-## Install the CLI
-
-To install Codezero via the command line, run the following command in your terminal:
-
-```bash
-curl -L https://releases.codezero.io/install-headless.sh | /bin/bash
-```
-
-## Log in and Start the Local Agent
-
-Log in to your Codezero account by running:
-
-```bash
-czctl auth login
-```
-
-Start the Codezero daemon (background service) by running:
-
-```bash
-czctl start
-```
-
-## Navigate to your Service Catalog
-
-You can now select the Teamspace from the Teamspace List in the top left corner of your browser window.
-This will take you to the Service Catalog:
-
-![Service Catalog](./_media/service-catalog.jpg)
+Once a Teamspace is setup and certified, individual developers can then install the Codezero local tools in order to work with the Teamspace. Developers will not require credentials for the Kubernetes cluster as they authenticate to the Teamspace via the Hub. We currently support Github and Google authentication.
diff --git a/docs/guides/installing.mdx b/docs/guides/installing.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 4
 ---
 
 import AppInstall from '../_fragments/app-install.md'

diff --git a/docs/tutorials/kubernetes-quickstart.md → docs/guides/kubernetes-quickstart.md b/docs/tutorials/kubernetes-quickstart.md → docs/guides/kubernetes-quickstart.md
@@ -1,20 +1,21 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 ---
 
-# Kubernetes Cluster QuickStart
+# Kubernetes QuickStart
 
-Codezero and the Sample Project is quite lightweight and work fine on a single node 4 core cluster or a two node 2 core cluster.
+## Overview
+
+You will require a Kubernetes cluster before you can create a Teamspace. If you are just evaluating Codezero, you may safely use your own cluster and project as uninstalling Codezero is pretty straight forward. Alternatively, we have provided a Sample Project for learning. Codezero and the Sample Project is lightweight and work fine on a single node 4 core cluster or a two node 2 core cluster.
 
 If you do not have a Kubernetes cluster, here is a list of providers who provide managed Kubernetes.
 Most will give you more than enough credits to get the basics.
-Of course, you can also follow the [Kubernetes the Hard Way](https://github.com/kelseyhightower/kubernetes-the-hard-way) guide if you would like to set up your own cluster from scratch.
 
 - [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks/)
 - [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/services/kubernetes-service/#overview)
-- [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine)
-- [DigitalOcean Kubernetes](https://try.digitalocean.com/codezero/)
 - [Civo](https://www.civo.com/)
+- [DigitalOcean Kubernetes](https://try.digitalocean.com/codezero/)
+- [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine)
 
 We recommend you use the service your organization uses.
 We have put together a short guide on using DigitalOcean and Civo as we have found these to be especially easy to get started with.

diff --git a/docs/guides/teamspace-setup.md b/docs/guides/teamspace-setup.md
@@ -4,42 +4,48 @@ sidebar_position: 3
 
 # Teamspace Setup
 
-Teamspaces are vanilla Kubernetes clusters with Codezero installed. We strive to make it really easy for you to get up and running with Codezero. Once you have a Kubernetes cluster setup, it will only take you a few more minutes to add Teamspace capabilities.
+Teamspaces are vanilla Kubernetes clusters with Codezero installed. The following guide will step you through registering a Teamspace and certifying it for development use. This should take about 10 minutes to complete.
 
-## Login to Hub
+## Create a Codezero Hub Account
 
-Log in to the [Codezero Hub](https://hub.codezero.io) and navigate to Settings > Teamspaces:
+Sign up or log in to the [Codezero Hub](https://hub.codezero.io). The onboarding wizard will guide you through creating an organization and your first Teamspace.
 
-![Teamspace Settings](./_media/ts-settings.jpg)
+The Hub allows you to register and certify Teamspaces. This is also where you can invite and administer members of the Teamspace. While the Hub provides a graphical user interface equivalent to the `czctl` command line tool, all services either run on your local machine or in the Kubernetes cluster.
 
-## Add Teamspace
+## Register a Teamspace on Hub
 
-Click _Add Teamspace_ to name and create your Teamspace.
+On the Profile menu, click on _Settings_ and then select _Teamspaces_. Click _Add Teamspace_ to name and register your Teamspace name.
 
 ![Teamspace Create](./_media/ts-create.jpg)
 
-## Install Codezero
+## Install Codezero in your Cluster
 
-Now that you have registered a Teamspace, click on _Helm Install_ to copy the helm install string. This install command is unique to your cluster. It includes a one-time token that is used to certify the Teamspace.
+After registering your Teamspace you need to install the _Codezero System_ onto a Kubernetes cluster. Click on _Helm Install_ to copy the Helm install command. This install command is unique to your cluster. It includes a one-time token that is exchanged with the Hub to certify the Teamspace.
 
-Once installed, the cluster will use this one-time token to securely send a Certificate Signing Request which will then Certify the cluster.
+![Install Codezero](./_media/ts-helm.jpg)
 
-```bash
-helm repo add --force-update codezero https://charts.codezero.io
-helm install --create-namespace --namespace=codezero --set space.token=<ONE-TIME TOKEN> \
-    codezero codezero/codezero
-```
-
-![Teamspace Install](./_media/ts-helm.jpg)
+## Certification
 
-## Wait for Certification
+The Codezero System installs into the `codezero` namespace and should take less than a minute to start depending on how long it takes to provision a LoadBalancer. Once ready, you should see the Certification column change to _Certified_ and shortly thereafter, you should see an IP address or Host Name show up under DNS. Your Teamspace is ready for use.
 
-Finally, you should see the Certification column change to _Certified_ and shortly thereafter, you should see an IP address or Host Name show up under _DNS_. At this time, your Teamspace is ready for use.
+Certification ensures secure communications between the Codezero System in cluster and the Hub.
 
 You can now select the Teamspace from the _Teamspace List_ in the navigation panel. This will take you to the _Service Catalog_:
 
 ![Teamspace Install](./_media/ts-certified.jpg)
 
+## Uninstalling Codezero
+
+Codezero may be removed from the Kubernetes cluster at any time. It is recommended that you close all Consume and Serve sessions prior to uninstalling.
+
+To uninstall, run:
+
+```bash
+helm -n codezero uninstall codezero
+```
+
+You can then go into the Hub and delete the Teamspace.
+
 ## Troubleshooting
 
 ### Rotate Certificate
@@ -60,4 +66,20 @@ The Codezero _System_ service will fail to start if it is unable to obtain the D
 
 ```bash
 kubectl -n codezero delete pod system-<RANDOM>
-```
+```
+
+### Locating Codezero Residue
+
+Codezero does not use any Custom Resource Definitions or finalizers. In the event that you need to lookup resources added or modified by Codezero, you can use the following `kubectl` commands
+
+```bash
+kubectl get all --selector="app.kubernetes.io/managed-by"=codezero --all-namespaces
+```
+
+If you are looking for residue in a specific namespace, use:
+
+```bash
+kubectl -n <NAMESPACE> get all --selector="app.kubernetes.io/managed-by"=codezero
+```
+
+You should close all Consume and Serve sessions prior to cleaning up residue in which case the Codezero System controller will perform the cleanup for you. If for whatever reason, it does not, you can remove the resources found and re-deploy your application to get back to a clean state.
diff --git a/docs/guides/using-desktop-app.mdx b/docs/guides/using-desktop-app.mdx
diff --git a/docs/welcome/architecture.md → docs/references/architecture.md b/docs/welcome/architecture.md → docs/references/architecture.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 1
 ---
 
 # Architecture

diff --git a/docs/references/changelog.md b/docs/references/changelog.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Release Notes

diff --git a/docs/references/command-line.md b/docs/references/command-line.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 # CLI Reference

diff --git a/docs/tutorials/_fragments/architecture.md b/docs/tutorials/_fragments/architecture.md
@@ -0,0 +1,9 @@
+```mermaid
+flowchart LR
+    User(Ingress) --- |HTTP /| Frontend((Frontend))
+    Frontend ---|Websocket| Sockets((Sockets))
+    Frontend --- |HTTP|Core((Core))
+    Core ---|TCP| Database[(Database)]
+    Core ---|HTTP| Leaf((Leaf))
+    User --- |HTTP /api| Core
+```
diff --git a/docs/tutorials/_media/core.png b/docs/tutorials/_media/core.png
diff --git a/docs/tutorials/_media/modheader.png b/docs/tutorials/_media/modheader.png
diff --git a/docs/tutorials/_media/sample.png b/docs/tutorials/_media/sample.png
diff --git a/docs/tutorials/_media/serve_browser.png b/docs/tutorials/_media/serve_browser.png
diff --git a/docs/tutorials/_media/service_catalog.png b/docs/tutorials/_media/service_catalog.png
diff --git a/docs/tutorials/app.mdx b/docs/tutorials/app.mdx
@@ -0,0 +1,16 @@
+---
+sidebar_position: 5
+---
+
+# Using the UI
+
+import ServiceCatalogImg from './_media/service_catalog.png'
+
+The Codezero Hub has a built in UI that is twofold. The Hub is where one can provision Teamspaces but also holds the Service Catalog where developers can Consume services as well as Serve up Variants.
+
+The following image highlights elements of the Service Catalog UI:
+
+
+<div class="text--center">
+  <img width="80%" src={ServiceCatalogImg}/>
+</div>