Merge pull request #237 from c6o/doc-improvements

doc improvements

docs/concepts/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Concepts",
+  "position": 5,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/references/architecture.md → docs/concepts/architecture.md

@@ -6,10 +6,12 @@ sidebar_position: 1
 
 ## Overview
 
-Codezero is made up of components that run locally on your developer workstation, in the Kubernetes cluster and a central cloud hosted Hub. The following color code identifies where the sub-components identified below run. 
+Codezero is made up of components that run locally on your developer workstation, in the Kubernetes cluster and a central cloud hosted Hub. The following color code identifies where the sub-components identified below run.
+
 * HUB (orange) is hosted by Codezero.
 * TEAMSPACE is the System and Operator (pink) components installed in your cluster.
 * The CLI, Desktop App and Daemon are installed and run on your LOCAL development machine.
+
 ```mermaid
 %%{init: {"theme": "forest", "themeCSS": [
     "[id*=entity-HUB] .er.entityBox { fill: orange;}",
@@ -21,6 +23,7 @@ erDiagram
     TEAMSPACE
     LOCAL
 ```
+
 This diagram defines all the components that make up Codezero:
 
 ```mermaid
@@ -64,7 +67,7 @@ The Operator manages Serve resources in the Kubernetes cluster.
 The local agent is composed of:
 
 1. A CLI and Daemon (aka `czctl`)
-2. A Desktop App (Codezero.app) 
+2. A Desktop App (Codezero.app)
 
 ### Daemon / CLI
 

docs/concepts/vpn.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 2
+---
+
+# VPNs and Traffic Shaping
+
+In many ways, Codezero works like a Virtual Private Network (VPN). Unlike a VPN however, Codezero only handles traffic related to services in a Teamspace. 
+You can use a VPN while using Codezero and both will coexist without interfering with each other.
+
+Codezero works by creating Virtual Interfaces for services running in the Teamspace and maintains entries in the `/etc/hosts` for these interfaces.
+
+Codezero adds DNS entries to the `/etc/hosts` file that is part of MacOS and most Linux implementations. 
+On Windows, Codezero modifies the appropriate Windows hosts file which in turn, propagates entries for the _Windows Subsystem for Linux_.
+
+When Codezero's Daemon is running, you will see entries in `/etc/hosts/` file, between the following markers
+
+```text
+###
+# CODEZERO
+# This section is managed by Codezero. Do not edit manually.
+...
+...
+# /CODEZERO
+###
+```
+
+As you Consume in-cluster services, you will see entries in this section appear, like below:
+
+```text
+127.72.0.0 sample-project-leaf
+127.72.0.0 sample-project-leaf.sample-project
+127.72.0.0 sample-project-leaf.sample-project.svc
+127.72.0.0 sample-project-leaf.sample-project.svc.cluster.local
+```
+
+These entries help map your in-cluster services to local names and allow you to work with remote services as though they are local.
+
+:::caution
+Do not modify the markers or the content between the markers. This will cause Codezero to malfunction!
+
+Currently, Codezero maps ports to the 127.72.0.0/14 range but local apps that bind to 0.0.0.0 or localhost can encounter port conflicts as they attempt to bind to all local interfaces. Also, please note that the local Codezero IP range above is subject to change.
+:::

docs/getting-started/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Getting Started",
+  "position": 2,
+  "link": {
+    "type": "doc",
+    "id": "getting-started/index"
+  }
+}

docs/guides/getting-started.md → docs/getting-started/index.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+slug: /getting-started
 ---
 
 # Getting Started
@@ -12,6 +12,6 @@ These are the general steps for setting up a Teamspace. Apart from setting up a
 1. Install the Codezero System [on the Kubernetes cluster](https://docs.codezero.io/guides/teamspace-setup#install-codezero-in-your-cluster) in order to Certify it as a Teamspace
 1. Invite team members to the Organization
 
-Once a Teamspace is set up and certified, individual developers can then [install the Codezero local tools](https://docs.codezero.io/guides/installing) to work with the Teamspace. Developers will not require credentials for the Kubernetes cluster as they authenticate to the Teamspace via the Hub. 
+Once a Teamspace is set up and certified, individual developers can then [install the Codezero local tools](https://docs.codezero.io/guides/installing) to work with the Teamspace. Developers will not require credentials for the Kubernetes cluster as they authenticate to the Teamspace via the Hub.
 
 NOTE: We currently support Github and Google authentication.

docs/guides/installing.mdx → docs/getting-started/installation.md

@@ -1,8 +1,8 @@
 ---
-sidebar_position: 4
+sidebar_position: 1
 ---
 
-# Installing Codezero Local Agent
+# Installing Local Agent
 
 Codezero's developer tools assist in the development/testing of Kubernetes applications through a Command-Line Interface (CLI) and a Desktop application.
 
@@ -26,14 +26,15 @@ import TabItem from '@theme/TabItem';
 
    1. Download the latest version for your CPU architecture type:
 
-   | Arch Type | URL                                                               |
-   | --------- | ----------------------------------------------------------------- |
-   | amd64     | https://releases.codezero.io/app/latest/Codezero-latest-x64.dmg   |
-   | arm64     | https://releases.codezero.io/app/latest/Codezero-latest-arm64.dmg |
-   
+   | Arch Type | URL                                                                                                                                    |
+   | --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+   | amd64     | [https://releases.codezero.io/app/latest/Codezero-latest-xd64.dmg](https://releases.codezero.io/app/latest/Codezero-latest-x64.dmg)    |
+   | arm64     | [https://releases.codezero.io/app/latest/Codezero-latest-arm64.dmg](https://releases.codezero.io/app/latest/Codezero-latest-arm64.dmg) |
+
    2. Drag the Codezero application to the Applications folder.
-   
+
    Alternatively you can use [homebrew](https://brew.sh):
+
    ```bash
    brew install --cask c6o/tap/codezero-app
    ```
@@ -44,13 +45,14 @@ import TabItem from '@theme/TabItem';
 
    1. Download the latest version for your CPU architecture type:
 
-   | Arch Type | URL                                                                    |
-   | --------- | ---------------------------------------------------------------------- |
-   | amd64     | https://releases.codezero.io/app/latest/CodezeroSetup-latest-x64.exe   |
-   | arm64     | https://releases.codezero.io/app/latest/CodezeroSetup-latest-arm64.exe |
-   
+   | Arch Type | URL                                                                                                                                              |
+   | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+   | amd64     | [https://releases.codezero.io/app/latest/CodezeroSetup-latest-x64.exe](https://releases.codezero.io/app/latest/CodezeroSetup-latest-x64.exe)     |
+   | arm64     | [https://releases.codezero.io/app/latest/CodezeroSetup-latest-arm64.exe](https://releases.codezero.io/app/latest/CodezeroSetup-latest-arm64.exe) |
+
    2. Double click on the setup exe.
 </TabItem>
+
 </Tabs>
 
 ## Command-Line Interface (CLI)
@@ -68,13 +70,15 @@ The Desktop application contains the CLI. You only need to install the CLI when
    ```bash
    brew install c6o/tap/codezero
    ```
+
 </TabItem>
 <TabItem value="scoop" label="Scoop">
    To install Codezero with [Scoop](https://scoop.sh) on Windows, run:
 
    ```
    scoop bucket add codezero https://github.com/c6o/scoop-codezero.git;scoop install codezero
    ```
+
 </TabItem>
 </Tabs>
 
@@ -88,17 +92,19 @@ The Desktop application contains the CLI. You only need to install the CLI when
 
    | Arch Type | URL                                                             |
    | --------- | --------------------------------------------------------------- |
-   | amd64     | https://releases.codezero.io/latest/headless-darwin-amd64.tar.gz |
-   | arm64     | https://releases.codezero.io/latest/headless-darwin-arm64.tar.gz |
+   | amd64     | [https://releases.codezero.io/latest/headless-darwin-amd64.tar.gz](https://releases.codezero.io/latest/headless-darwin-amd64.tar.gz) |
+   | arm64     | [https://releases.codezero.io/latest/headless-darwin-arm64.tar.gz](https://releases.codezero.io/latest/headless-darwin-arm64.tar.gz) |
 
    2. Unzip the file: `tar -xzvf headless-*.tar.gz`
 
    Optionally, install the binary in a location where you can execute it globally (for example, `/usr/local/bin`).
 
    Alternatively you can use the following command to install the latest version into `/usr/local/bin`:
+
    ```bash
    curl -L https://releases.codezero.io/install-headless.sh | /bin/bash
    ```
+
 </TabItem>
 <TabItem value="linux" label="Linux">
    To install Codezero without a package manager on Linux:
@@ -107,17 +113,19 @@ The Desktop application contains the CLI. You only need to install the CLI when
 
    | Arch Type | URL                                                             |
    | --------- | --------------------------------------------------------------- |
-   | amd64     | https://releases.codezero.io/latest/headless-linux-amd64.tar.gz  |
-   | arm64     | https://releases.codezero.io/latest/headless-linux-arm64.tar.gz  |
+   | amd64     | [https://releases.codezero.io/latest/headless-linux-amd64.tar.gz](https://releases.codezero.io/latest/headless-linux-amd64.tar.gz)  |
+   | arm64     | [https://releases.codezero.io/latest/headless-linux-arm64.tar.gz](https://releases.codezero.io/latest/headless-linux-arm64.tar.gz)  |
 
    2. Unzip the file: `tar -xzvf headless-*.tar.gz`
 
    Optionally, install the binary in a location where you can execute it globally (for example, `/usr/local/bin`).
-   
+
    Alternatively, you can use the following command to install the latest version into `/usr/local/bin`:
+
    ```bash
    curl -L https://releases.codezero.io/install-headless.sh | /bin/bash
    ```
+
 </TabItem>
 <TabItem value="windows" label="Windows">
    To install Codezero without a package manager on Windows:
@@ -126,13 +134,14 @@ The Desktop application contains the CLI. You only need to install the CLI when
 
    | Arch Type | URL                                                            |
    | --------- | -------------------------------------------------------------- |
-   | amd64     | https://releases.codezero.io/latest/headless-windows-amd64.zip |
-   | arm64     | https://releases.codezero.io/latest/headless-windows-arm64.zip |
+   | amd64     | [https://releases.codezero.io/latest/headless-windows-amd64.zip](https://releases.codezero.io/latest/headless-windows-amd64.zip) |
+   | arm64     | [https://releases.codezero.io/latest/headless-windows-arm64.zip](https://releases.codezero.io/latest/headless-windows-arm64.zip) |
 
    2. Unzip the file.
 
    3. Add the path to the unzipped `czctl.exe` file to your `Path` environment variable.
       To learn how to update environment variables, see the
       [Microsoft PowerShell documentation](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.3#saving-changes-to-environment-variables).
 </TabItem>
+
 </Tabs>