Refactor MVK documentation

templates; streamline navigation, add new guides, and enhance clarity in prerequisites, configuration, and run instructions for Gcloud setups.

astro.config.mjs

@@ -23,41 +23,11 @@ export default defineConfig({
 			sidebar: [
 				{
 					label: 'MVK',
-					items: [
+					autogenerate: { directory: 'mvk' },
-						// Each item here is one entry in the navigation menu.
-						{ label: 'Minimal Viable Kubernetes', slug: 'mvk/intro' },
-					],
 				},
-				{
-					label: 'infctl',
-					items: [
-						// Each item here is one entry in the navigation menu.
-						{ label: 'Introduction', slug: 'infctl/intro' },
-						{ label: 'Quick Start Guide', slug: 'infctl/quick-start' },
-						{ label: 'Configuration', slug: 'infctl/configuration' },
-					],
-				},
-				// {
-				// 	label: 'MVK',
-				// 	autogenerate: { directory: 'mvk' },
-				// },
 				{
 					label: 'Microlearning',
 					autogenerate: { directory: 'guides' },
-
-
-
-
-					// items: [
-					// 	{ label: 'Local Dev Environment', slug: 'guides/dev-env' },
-					// 	{ label: 'Create a Local K3d Instance', slug: 'guides/local-k3d' },
-					// 	{ label: 'Initial Pipeline Run', slug: 'guides/infctl-first-run' },
-					// 	{ label: 'Create a vagrant 3 node cluster', slug: 'guides/local-vagrant-cluster' },
-					// 	{ label: 'Add Longhorn Storage', slug: 'guides/local-vagrant-cluster-storage' },
-					// 	{ label: 'Add Ingress', slug: 'guides/local-vagrant-cluster-ingress' },
-
-
-					// ],
 				},
 				{
 					label: 'MVK Templates',

src/content/docs/index.mdx

@@ -8,7 +8,7 @@ hero:
     file: ../../assets/mvk.png
   actions:
     - text: MVK Guide
-      link: /mvk/intro/
+      link: /mvk/1-introduction/goals-limitation-design-use-cases/
       icon: right-arrow
     - text: infctl and mvk source
       link: https://codeberg.org/headshed/infctl-cli

src/content/docs/mvk/1. Introduction/goals-limitation-design-use-cases.md

@@ -1,17 +1,29 @@
 ---
-title: MVK Introduction
+title: Goals, Limitations, Design, Use Cases
 description: introducing minimal viable Kubernetes and its guiding principles 
 ---
 
-Kubernetes is complicated 
+## Goals
 
-Additionally, K8s is designed with cloud in mind.
+Minimal Viable Kubernetes has the following goals:
 
-Thus, self hosting options can be limiting.
+* CLI friendly and first
+* Promotes Infrastructure as Code
+* Portablity across cloud and on-prem
+* Openness and keeping it simple
+* Avoid proprietary lock in
+
+Kubernetes is complicated.
+
+K8s is designed with cloud in mind.
+
+Self hosted options can be limiting.
 
 ## Limitations
 
-Out of the box, Kubernetes expects key components of infrastructure to be present. For example, ingress, storage and load balancers. 
+MVK addresses the limitations of Kubernetes 'out of the box' for self-hosted implementation.
+
+On its own, Kubernetes expects key components of infrastructure to be present. For example, ingress, storage and load balancers. 
 
 If any of these are not present, they will need to be supplied in a form that Kubernetes can consume them.
 
@@ -39,7 +51,7 @@ It can also reduce costs, provided that its users are already, or become, famili
 
 A greater understanding of k8s results in us all becoming less reliant on others providing this as a service for us. It protects our industry from losing these skills entirely. 
 
-**Above all it can gain control over our own digital sovereignty.**
+**MVK can help give us control of our digital sovereignty.**
 
 
 

src/content/docs/mvk/2. infctl/020-quick-start.md

@@ -0,0 +1,21 @@
+---
+title: Quick Start 
+description: A guide to setting up MVK quickly.
+---
+
+`infctl` is a command line tool used by  MVK to orchestrate code.
+
+It makes scripted infrastructure as code simpler and easier to run, manage and support.
+
+You can think of it as a 'simpler pipeline'.
+
+Install `infctl` command line tool with
+
+```bash
+curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/install.sh | bash
+```
+
+Alternatively, go to [Releases](https://codeberg.org/headshed/infctl-cli/releases) to find a current version for your Operating System, download it and place a copy in your `PATH`.
+
+
+

src/content/docs/mvk/2. infctl/030-configuration.md

@@ -0,0 +1,54 @@
+---
+title: Configuration
+description: infctl configuration 
+---
+
+`infctl` uses `json` files for configuration.
+
+It is designed around the idea of pipelines where each pipeline performs a series of steps.
+
+A short, 2 step pipeline configuration can look like :
+
+```json
+[
+  {
+    "name": "ensure inf namespace exists",
+    "function": "k8sNamespaceExists",
+    "params": ["infctl"],
+    "retryCount": 0,
+    "shouldAbort": true
+  },
+  {
+    "name": "create php configmap",
+    "function": "RunCommand",
+    "params": ["./scripts/create_php_configmap_ctl.sh"],
+    "retryCount": 0,
+    "shouldAbort": true
+  }
+]
+```
+
+Each Object is a task.
+
+Object task records are executed in a `[]` list and in sequence.
+
+Each task has a `name` to be displayed in logs.
+
+Each task calls a `Function` that is registered within `infctl` and that accepts `params` string, which are any parameters to be passed to that function, script or executable. The simplest example being  `RunCommand` which accepts the path to a script or executable as its `params`. This can be anything but can be as simple as :
+
+```bash
+echo "hello world"
+
+exit 0
+```
+
+So `infctl` is unlimited as to what it can use in its pipeline files to achieve any kind of automation.
+
+If a task fails ( the script or program that is run returns a non zero value ) it may be re-tried up to `retryCount` times.
+
+If a task fails the pipeline will stop running unless `shouldAbort` is set to false, in which case, the pipeline will continue to run with the next step item in the list.
+
+
+
+
+

src/content/docs/templates/1. Gcloud single node/001-prereques.md

@@ -3,5 +3,27 @@ title: Pre-Requisites
 description: A guide to creating a single Gcloud MVK node.
 ---
 
-### 1. PREREQS
+we need to run this at least once to ensure we have tooling available ...
 
+```bash
+cd ${PATH_TO_infctl-cli}/infctl-cli # where we checked out infct-cli to
+./gcloud/tf/scripts/pre-flight-checks.sh
+```
+
+```
+✅ tofu is installed,...
+
+✅ gcloud is installed,...
+
+✅ kubectl is installed,...
+
+✅ envsubst is installed,...
+
+# .....
+
+✅ Pre-flight checks passed. You are ready to proceed 🙂
+```
+
+hopefully, we have no errors. 
+
+Follow instructions to install any missing dependencies.

src/content/docs/templates/1. Gcloud single node/010-configure.md

@@ -3,5 +3,11 @@ title: Configure
 description: A guide to creating a single Gcloud MVK node.
 ---
 
-### 2. CONFIGURE
+```bash
-
+[ -f .env ] || cp -v .env.gcloud-example .env
+# edit to include
+export PROJECT_NAME="the name of your gcp project, often referred to as the project"
+export EMAIL="your email address to identify yourself with letsencrypt"
+export APP_DOMAIN_NAME="your domain name for the app, e.g., frgdr.some-domain.com"
+export INSTALL_FORGEJO="true"
+```

src/content/docs/templates/1. Gcloud single node/030-run.md

@@ -3,4 +3,12 @@ title: Run
 description: A guide to creating a single Gcloud MVK node.
 ---
 
-### 3. RUN
+```bash
+# RUN
+LOG_FORMAT=none infctl -f ./gcloud/tf/scripts/build-gcloud-k3s-pipeline-wait-dns.json
+```
+
+At the end of the pipeline we will see an ip address displayed of the VM instance the terraform has created.
+
+You will need to edit an A-record in your DNS to point your $APP_DOMAIN_NAME
+

src/content/docs/templates/2. Gcloud 3 node coming soon/001-prereques.md

@@ -0,0 +1,31 @@
+---
+title: Pre-Requisites
+description: A guide to creating a single Gcloud MVK node.
+---
+
+### 👷 coming soon ...
+
+we need to run this at least once to ensure we have tooling available ...
+
+```bash
+cd ${PATH_TO_infctl-cli}/infctl-cli # where we checked out infct-cli to
+./gcloud/tf/scripts/pre-flight-checks.sh
+```
+
+```
+✅ tofu is installed,...
+
+✅ gcloud is installed,...
+
+✅ kubectl is installed,...
+
+✅ envsubst is installed,...
+
+# .....
+
+✅ Pre-flight checks passed. You are ready to proceed 🙂
+```
+
+hopefully, we have no errors. 
+
+Follow instructions to install any missing dependencies.

src/content/docs/templates/2. Gcloud 3 node coming soon/010-configure.md

@@ -0,0 +1,15 @@
+---
+title: Configure
+description: A guide to creating a single Gcloud MVK node.
+---
+
+### 👷 coming soon ...
+
+```bash
+[ -f .env ] || cp -v .env.gcloud-example .env
+# edit to include
+export PROJECT_NAME="the name of your gcp project, often referred to as the project"
+export EMAIL="your email address to identify yourself with letsencrypt"
+export APP_DOMAIN_NAME="your domain name for the app, e.g., frgdr.some-domain.com"
+export INSTALL_FORGEJO="true"
+```

src/content/docs/templates/2. Gcloud 3 node coming soon/030-run.md

@@ -0,0 +1,6 @@
+---
+title: Run
+description: A guide to creating a single Gcloud MVK node.
+---
+
+### 👷 coming soon ...