astro.config.mjs

@@ -1,59 +1,38 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
-import starlightHeadingBadges from 'starlight-heading-badges'
 
 // https://astro.build/config
 export default defineConfig({
 	integrations: [
 		starlight({
-			plugins: [starlightHeadingBadges()],
 			title: 'MinimalViableK8s',
 			social: [{ icon: 'github', label: 'GitHub', href: 'https://codeberg.org/headshed/infctl-cli' }],
-			head: [
-				{
-					tag: 'script',
-					attrs: {
-						defer: true,
-						'data-domain': 'mvk.headshed.dev',
-						src: 'https://stats.headshed.dev/js/script.js'
-					}
-				}
-			],
 			sidebar: [
 				{
 					label: 'MVK',
 					items: [
 						// Each item here is one entry in the navigation menu.
-						{ label: 'Minimal Viable Kubernetes', slug: 'mvk/intro' },
+						{ label: 'Minimal Viable Kubernetes', slug: 'guides/mvk' },
 					],
 				},
 				{
 					label: 'infctl',
 					items: [
 						// Each item here is one entry in the navigation menu.
-						{ label: 'Introduction', slug: 'infctl/intro' },
+						{ label: 'Introduction', slug: 'guides/intro' },
-						{ label: 'Quick Start Guide', slug: 'infctl/quick-start' },
+						{ label: 'Quick Start Guide', slug: 'guides/quick-start' },
-						{ label: 'Configuration', slug: 'infctl/configuration' },
+						{ label: 'Configuration', slug: 'guides/configuration' },
 					],
 				},
 				{
 					label: 'Microlearning',
-					autogenerate: { directory: 'guides' },
+					items: [
-
+						// Each item here is one entry in the navigation menu.
-
+						{ 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' },
-					// 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: 'Reference',

package.json

@@ -12,7 +12,6 @@
   "dependencies": {
     "@astrojs/starlight": "^0.34.5",
     "astro": "^5.6.1",
-    "sharp": "^0.34.2",
+    "sharp": "^0.34.2"
-    "starlight-heading-badges": "^0.6.0"
   }
 }

src/content/docs/guides/001-dev-env.md

@@ -1,93 +0,0 @@
----
-title: Pre requisites for development
-description: A guide to checking a local environment.
----
-
-MVK will help create a working kubernetes environment but requires some tooling. Running a test script will help to check your current environment and avoid failures later on.    
-
-## Pre Flight Checks
-
-Run `dev-pre-flight-checks.sh` command line tool with
-
-```bash
-curl -sL https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh | bash
-```
-
-Alternatively, download https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh locally, check over what it does, `chmod +x dev-pre-flight-checks.sh` and run `./dev-pre-flight-checks.`
-
-the following executables are checked to be in your `$PATH`:
-
-"infctl" "pwgen" "kubectl" "k3d" "helm" "jq" "docker" "vagrant" "git"
-
-if any of these are missing, an MVK development environment may fail.
-
-### Note for windows users
-
-Linux and Mac already have `bash` and often `git` installed as part of a default developer environment, however Windows may not, so for MVK, we can use [Git Bash](https://git-scm.com/downloads), so check you have this installed on Windows if not already. 
-
-Windows will need `jq` to be installed by [downloading](https://jqlang.org/download/) it or installing with `winget install jqlang.jq.`
-
-Use Git Bash from here on to run `infctl` commands as they will require for there to be a bash shell to run any of its plugins.
-
-## Install Pre-Requisites
-
-`infctl` - see [quick start](/guides/quick-start/)
-
-`pwgen`, `jq` are typically available in package managers
-
-To install `pwgen` or `jq`:
-
-**On macOS (using Homebrew):**
-```bash
-brew install pwgen jq
-```
-
-**On Linux (Debian/Ubuntu):**
-```bash
-sudo apt-get update
-sudo apt-get install pwgen jq
-```
-
-**On Linux (Fedora):**
-```bash
-sudo dnf install pwgen jq
-```
-
-To download `kubectl`, visit the official Kubernetes documentation: [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/). Follow the instructions for your operating system.
-
-
-To install `k3d` go to [k3d installation](https://k3d.io/stable/#installation) and follow their guide
-
-To install `helm` got to [helm install](https://helm.sh/docs/intro/install/) and follow their guide
-
-Docker can be installed in a variety of ways but for most Windows and Mac users [docker desktop](https://www.docker.com/products/docker-desktop/) can be an easy option
-
-For Linux users, [docker engine install](https://docs.docker.com/engine/install/) is more often than not the better option.
-
-Which ever path you take to install Docker, any of the above will work but if you are interesting in really getting to know Kubernetes, it is would be really good to go for a Linux based solution as this is typically what Kubernetes is likely to be running on in any production grade environment.
-
-To install `vagrant`, visit the [official Vagrant downloads page](https://www.vagrantup.com/downloads) and choose the installer for your operating system.
-
-**Note:** Vagrant typically requires a compatible hypervisor to manage virtual machines. The most common option is **VirtualBox**, which works on Windows, macOS, and Linux. You can download VirtualBox from the [official site](https://www.virtualbox.org/wiki/Downloads).
-
-- On **Windows**, you may also use **Hyper-V** if available.
-- On **Linux**, **KVM** is a popular alternative.
-
-For most users, installing VirtualBox alongside Vagrant is the simplest and most widely supported setup.
-
-**Example installation on macOS (using Homebrew):**
-```bash
-brew install --cask vagrant virtualbox
-```
-
-**Example installation on Ubuntu/Debian:**
-```bash
-sudo apt-get update
-sudo apt-get install vagrant virtualbox
-```
-
-After installation, verify both are available in your `$PATH` by running:
-```bash
-vagrant --version
-VBoxManage --version
-```

src/content/docs/guides/dev-env.md

@@ -0,0 +1,53 @@
+---
+title: Local Development Environment
+description: A guide to checking a local environment.
+---
+
+Run `dev-pre-flight-checks.sh` command line tool with
+
+```bash
+curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh | bash
+```
+
+Alternatively, download https://codeberg.org/headshed/infctl-cli/raw/branch/main/scripts/dev-pre-flight-checks.sh locally, check over what it does, `chmod +x dev-pre-flight-checks.sh` and run `./dev-pre-flight-checks.`
+
+the following executables are checked to be in your `$PATH`:
+
+"infctl" "pwgen" "kubectl" "k3d" "helm" "jq" "docker"
+
+if any of these are missing, a development environment cannot be created.
+
+`infctl` - see [quick start](/guides/quick-start/)
+
+`pwgen`, `jq` are typically available in package managers
+
+To install `pwgen` or `jq`:
+
+**On macOS (using Homebrew):**
+```bash
+brew install pwgen jq
+```
+
+**On Linux (Debian/Ubuntu):**
+```bash
+sudo apt-get update
+sudo apt-get install pwgen jq
+```
+
+**On Linux (Fedora):**
+```bash
+sudo dnf install pwgen jq
+```
+
+To download `kubectl`, visit the official Kubernetes documentation: [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/). Follow the instructions for your operating system.
+
+
+To install `k3d` go to [k3d installation](https://k3d.io/stable/#installation) and follow their guide
+
+To install `helm` got to [helm install](https://helm.sh/docs/intro/install/) and follow their guide
+
+Docker can be installed in a variety of ways but for most Windows and Mac users [docker desktop](https://www.docker.com/products/docker-desktop/) can be an easy option
+
+For Linux users, [docker engine install](https://docs.docker.com/engine/install/) is more often than not the better option.
+
+Which ever path you take to install Docker, any of the above will work but if you are interesting in really getting to know Kubernetes, it is would be really good to go for a Linux based solution as this is typically what Kubernetes is likely to be running on in any production grade environment.

src/content/docs/guides/example.md

@@ -0,0 +1,11 @@
+---
+title: Example Guide
+description: A guide in my new Starlight docs site.
+---
+
+Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
+Writing a good guide requires thinking about what your users are trying to do.
+
+## Further reading
+
+- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework

src/content/docs/guides/infctl-first-run.md

@@ -1,9 +1,9 @@
 ---
-title: Initial Pipeline Run
+title: Creating Initial Infrastructure
 description: A guide to running infctl for the first time.
 ---
 
-having already cloned the `infctl-cli` see [K3d single instance](/guides/k3d/003-local-k3d/) change directory to where this code repository was checked out on your system.
+having already cloned the `infctl-cli` see [Create a local k3d instance](/guides/local-k3d/) change directory to where this code repository was checked out on your system.
 
 If necessary, re-run `scripts/create_k3d_cluster.sh` to create a new local cluster or just use one created earlier if you chose not to delete it.
 

src/content/docs/guides/intro.md

@@ -7,7 +7,7 @@ Kubernetes is complicated, so getting started can be a pain.
 
 There are many tools out there to create a development Kubernetes environment. 
 
-`infctl` is just another such tool, however it is designed with simplicity in mind, yet with a view to its use being extended to production and beyond.
+`infctl` is just another such tool, however it is designed with simplicity in mind, yet with a view to it being extended into production and beyond.
 
 
 

src/content/docs/guides/k3d/009-development-releases.md

@@ -1,43 +0,0 @@
----
-title: Operational consideration     
-description: Thinking about security and service management early on.
----
-
-When we create code and infrastructure for development, it is in preparation for production.
-
-Breaks in development workflow ultimately delay releases to production. So adequate testing of our code helps ensure that others working with us do not have bad experiences.
-
-## Continuity 
-
-Continuity of the development workflow is frequently underpinned by 
-
-* applying secure coding practices to ensure we are not leaking secure data or opening our applications to be exploited by bad actors
-* adding feature tests to prove critical functionality is maintained
-* employing health and ping checks to ensure availability in deployments
-* creating anonymized test data that is functionally representative of that in live
-
-The above headlines are not exhaustive and, depending on our use case, may well become longer.
-
-This can be summarized as a 'shift left' of security and testing practice into early stages of the software development lifecycle.
-
-## Configuration
-
-From `infctl`'s pont of view, it creates for us a `config.json` file at run time if not already present that contains :
-
-```json
-{
-  "log_format": "<full|basic|none>",
-  "deployment_file": "<path as specified to this pipeline file>",
-  "deployment_type": "<development|pre-production|production where development is the default>",
-  "deployment_mode": "json"
-}
-```
-
-So unless we edit this file, the default `deployment_type` is that of `development`.
-
-It signifies that we have applied the above working practice.
-
-Our code and pipelines can be documented, version controlled and checked from development through to production readiness.
-
-
-

src/content/docs/guides/local-k3d.md

@@ -1,10 +1,8 @@
 ---
-title: K3d single instance
+title: Create a Local K3d Instance
 description: A guide to creating an initial local k3d instance.
 ---
 
-###### Use case :badge[development]{variant=success}
-
 clone the `infctl-cli` repo in order to have local access to its scripts, files and manifests to use later on.
 
 Where you put this is up to you but we will work on the assumption that this will be in `$HOME/projects` :

src/content/docs/guides/mvk.md

@@ -1,45 +1,37 @@
 ---
-title: MVK Introduction
+title: Minimal Viable Kubernetes 
 description: introducing minimal viable Kubernetes and its guiding principles 
 ---
 
-Kubernetes is complicated 
+Kubernetes is complicated but additional to this it is designed with cloud compute in mind.
-
-Additionally, K8s is designed with cloud in mind.
 
 Thus, self hosting options can be limiting.
 
-## Limitations
+Out of the box, Kubernetes expects key ingredients of infrastructure to be present. For example, ingress, storage and load balancers. 
-
-Out of the box, 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.
 
-Adding the missing pre-requisites can be a challenge. Even learning about Kubernetes, let alone setting up a development or 'lab' environment, can become time consuming. 
+Adding the missing pre-requisites can be a challenge. Even learning about Kubernetes, let alone setting up a development or 'lab' environment, can quickly become messy. 
 
-## Opinionated by design
+Knowing what to create in 'dev' as opposed to 'prod` may introduce inconsistent configurations and can result in adding technical debt.
-
-Knowing what to create in **development** as opposed to **production** may introduce inconsistency and technical debt.
 
 Production environments can also become complex, difficult to manage, even over engineered.
 
-Responding to these challenging scenarios, MVK provides tooling and design patterns aimed toward solving these issues.
+Responding to these challenging scenarios, Minimal Viable Kubernetes (MVK) provides tooling and design patterns aimed toward solving these issues.
 
 MVK helps create a minimal K8s setup and one which is a viable implementation of Kubernetes. Initially this may be used for test and development work, but extending this into production is also its goal. 
 
-## Use cases
-
 Typical use cases of MVK are aimed toward entirely self hosted environments. This may be outside of any managed Kubernetes or cloud platform, which are often as not proprietary in their design and provisioning of k8s. 
 
 The goals of MVK are to increase portability and reduce 'vendor lock in'. 
 
 It can also reduce costs, provided that its users are already, or become, familiar with Kubernetes and its day to day operational and management. 
 
-> We think that **everyone** should know more about Kubernetes. 
+*We think that **everyone** should know more about Kubernetes*. 
 
 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.**
+**Above all it can help us to gain control over our digital sovereignty.**
 
 
 

src/content/docs/guides/quick-start.md

@@ -3,7 +3,7 @@ title: Quick Start Guide
 description: A guide to setting up MVK quickly.
 ---
 
-Install `infctl` command line tool with
+Install `infctl` command line tool with a single command
 
 ```bash
 curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/install.sh | bash

src/content/docs/guides/vagrant/005-local-vagrant-cluster.md

@@ -1,54 +0,0 @@
----
-title: 3 node cluster
-description: A guide to creating a virtualized local k3s instance.
----
-
-###### Use case :badge[development]{variant=success} :badge[pre-production]{variant=caution}
-
-# Prerequisites 
-
-MVK on vagrant represents a 'real' 3 node VM in the cloud but running on a local, self-hosted environment.
-
-This is developed and tested on a single machine with >16G of memory, 8 cpus and around 500GB hard drive. 
-
-Your mileage may vary depending on CPU and memory but in my experience, 16Gig or more memory is better suited to this kind of work and ideally, more so. It is not uncommon to use 32Gig for a 'home lab' server / desktop these days. 
-
-# Getting Started
-
-Clone the [`infctl-cli`](https://codeberg.org/headshed/infctl-cli) repo in order to have local access to its scripts, files and manifests to use later on.
-
-Where you put this is up to you but we will work on the assumption that this will be in `$HOME/projects` :
-
-```bash
-mkdir -p $HOME/projects/
-cd $HOME/projects
-git clone https://codeberg.org/headshed/infctl-cli.git
-cd infctl-cli
-```
-
-## Familiarise yourself with ...
-
-[./scripts/install_vagrant_nodes.sh](https://codeberg.org/headshed/infctl-cli/src/branch/main/scripts/install_vagrant_nodes.sh) will run `vagrant up` on what is to be your local cluster.
-
-[`./scripts/configure_vagrant_k3s.sh`](https://codeberg.org/headshed/infctl-cli/src/branch/main/scripts/configure_vagrant_k3s.sh) checks and interogates the vagrant hosts to create an ansible inventory file for later use with Ansible.
-
-[`vagrant/dev/ubuntu/Vagrantfile`](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/Vagrantfile) is used by `vagrant` to coordinate the cluster and workstation build
-
-[`scripts/install_vagrant_workstation.sh`](https://codeberg.org/headshed/infctl-cli/src/branch/main/scripts/install_vagrant_workstation.sh) brings the workstation up after the server nodes have been established
-
-[`./vagrant/dev/ubuntu/ansible/provision_workstation.sh`](https://codeberg.org/headshed/infctl-cli/src/commit/bd222ce39e363bcdb536362d5dcb0699b1dbb2ee/vagrant/dev/ubuntu/ansible/provision_workstation.sh) is quite a bit longer and more involved than those previous, as it is used by `vagrant` to provision our workstation and uses [ansible scripts](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/ansible) to :
-* [ansible ping](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/ping_module.html) the 3 cluster nodes
-* [ansible-playbook](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html) install [`keepalived`](https://www.keepalived.org/) which MVK uses as a 'cheap loadbalancer' by which k3s can access the current, active k8s interface
-* ansible-playbook install the 3 node k3s cluster
-* ansible-playbook install the k8s config file onto the workstation for management of k8s
-* ansible-playbook install [`dnsmasq`](https://thekelleys.org.uk/dnsmasq/doc.html) for later use in development and testing the local cluster
-
-## Run the pipeline ...
-
-if you are ready to run the pipeline, this can be run in a single command with `infctl` which we can configure to use a pipeline file at [`pipelines/dev/vagrant-k3s.json`](https://codeberg.org/headshed/infctl-cli/src/branch/main/pipelines/dev/vagrant-k3s.json)
-
-This marshals each of the above tasks into a single, repeatable operation.
-
-```bash
-LOG_FORMAT=none infctl -f pipelines/dev/vagrant-k3s.json
-```

src/content/docs/guides/vagrant/006-local-vagrant-smoke-test.md

@@ -1,44 +0,0 @@
----
-title: Smoke test the cluster
-description: Basic smoke tests
----
-
-
-If all has gone well, a cluster will now be running on your local system comprising of 3 nodes and a workstation.
-
-We can check status by now switching directory to the vagrant dev folder and running a `vagrant status` command :
-
-
-```bash
-cd vagrant/dev/ubuntu/
-vagrant status
-Current machine states:
-
-vm1                       running (virtualbox)
-vm2                       running (virtualbox)
-vm3                       running (virtualbox)
-workstation               running (virtualbox)
-
-This environment represents multiple VMs. The VMs are all listed
-above with their current state. For more information about a specific
-VM, run `vagrant status NAME`.
-```
-To work on our cluster we must first connect to the `workstation` and then use `kubectl` commands to interact with `k3s` :
-```bash
-vagrant ssh workstation
-```
-From the workstation, use [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) to access our cluster
-```bash
-kubectl get nodes
-NAME   STATUS   ROLES                       AGE     VERSION
-vm1    Ready    control-plane,etcd,master   4h11m   v1.33.3+k3s1
-vm2    Ready    control-plane,etcd,master   4h11m   v1.33.3+k3s1
-vm3    Ready    control-plane,etcd,master   4h10m   v1.33.3+k3s1
-```
-
-
-
-
-
-
-If you have got this far, congratulation you have a locally hosted k3s cluster running in 3 virtual machines and a workstation that can be used to manage it using `kubectl` and `ansible`.

src/content/docs/guides/vagrant/010-local-vagrant-cluster-storage.md

@@ -1,32 +0,0 @@
----
-title: Add Longhorn Storage
-description: A guide to adding Longhorn storage.
----
-
-## Prerequisites
-
-This follows on from [Create a vagrant 3 node cluster](/guides/local-vagrant-cluster/) so be sure to complete that section before proceeding with this one.
-
-## Familiarise yourself with …
-
-A pipeline file [vagrant-longhorn.json](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/pipelines/vagrant-longhorn.json) uses 
-
-* [longhorn_prereqs.sh](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/scripts/longhorn_prereqs.sh) which uses an ansible playbook [install_longhorn_prereqs.yaml](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/ansible/install_longhorn_prereqs.yaml)
-* [install_longhorn.sh](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/scripts/install_longhorn.sh) `kubectl` installs longhorn storage
-* [wait_for_longhorn.sh](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/scripts/wait_for_longhorn.sh) waits for longhorn setup to be complete.
-
-## Run the pipeline …
-
-From the previous directory in our example which was `/home/user/projects/infctl-cli` we need to change directory `cd vagrant/dev/ubuntu/`
-
-so we can `ssh` to the workstation
-
-```bash
-vagrant ssh workstation
-```
-
-and once logged in to the workstation we can install longhorn with
-
-```bash
-LOG_FORMAT=basic infctl -f pipelines/vagrant-longhorn.json
-```

src/content/docs/guides/vagrant/015-local-vagrant-cluster-ingress.md

@@ -1,40 +0,0 @@
----
-title: Add Ingress
-description: A guide to adding ingress.
----
-
-## Prerequisites
-
-This section follows on from [Add Longhorn Storage](/guides/local-vagrant-cluster-storage/). Be sure to complete that before commencing with this.
-
-if not already shelled into the workstation, from `/home/user/projects/infctl-cli` we need to change directory to
-
-```bash
-cd vagrant/dev/ubuntu/
-```
-so we can ssh to the workstation
-
-```bash
-vagrant ssh workstation
-```
-
-## Familiarise yourself with …
-
-* [install_metallb.sh](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/scripts/install_metallb.sh) applies a kubernetes manifest to install metallb and then applies an `IPAddressPool` and `L2Advertisement` which will be used later by `traefik` to access a loadbalancer in order to expose services so that we can access them from outside of kubernetes. This is a key part of MVK and one which does not exist in Kubernetes as this is typically expected to be provided by a managed kubernetes cloud service.
-* [install_traefik.sh](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/scripts/install_traefik.sh) sets up some custom variables to enable an internal dashboard, ports for ingress, log level and loadbalancer.
-
-## Run the pipelines …
-
-The [metallb pipeline](https://codeberg.org/headshed/infctl-cli/src/branch/main/vagrant/dev/ubuntu/pipelines/vagrant-metallb.json) can be run with :
-
-
-```bash
-LOG_FORMAT=basic infctl -f pipelines/vagrant-metallb.json
-```
-
-traefik ingress can be installed with 
-
-```bash
-LOG_FORMAT=basic infctl -f pipelines/vagrant-ingress.json
-```
-

src/content/docs/guides/vagrant/020-security.md

@@ -1,35 +0,0 @@
----
-title: Operational consideration 
-description: using production like infra for securing our apps
----
-
-Running infrastructure on Vagrant is not generally intended for production use. More frequently, localized development and testing may be achieved using `k3d` and other containerized k8s environments.
-
-## Production grade
-
-However it is possible and useful to develop and test applications that are already running on  near to production grade infrastructure.
-
-We can test and prove deployments to be able to
-
-* be tested in a safer environment
-* able to cope with service interruptions due to a failing node
-* work with ingress 
-
-Single containerized k8s stacks lack their fully virtualized counterparts physical attributes such as CPU, memory, storage and networks.
-
-## Configuration
-
-From `infctl`'s pont of view, it creates for us a `config.json` file at run time if not already present that contains :
-
-```json
-{
-  "log_format": "<full|basic|none>",
-  "deployment_file": "<path as specifed to this pipeline file>",
-  "deployment_type": "<development|pre-production|production where development is the default>",
-  "deployment_mode": "json"
-}
-```
-
-We would logically change `deployment_type` to be `pre-production` for pipelines that have reached this stage.
-
-It is then obvious that our code has reached a stage that has been tested close to production.

src/content/docs/index.mdx

@@ -5,10 +5,10 @@ template: splash
 hero:
   tagline: Tools and patterns to deliver self hosted, minimal, viable k8s!
   image:
-    file: ../../assets/mvk.png
+    file: ../../assets/houston.webp
   actions:
     - text: MVK Guide
-      link: /mvk/intro/
+      link: /guides/mvk/
       icon: right-arrow
     - text: infctl and mvk source
       link: https://codeberg.org/headshed/infctl-cli

src/content/docs/reference/api-reference.md

@@ -3,56 +3,82 @@ title: API Reference
 description: Reference for infctl commands and functions.
 ---
 
-# INFCTL CLI API Reference
+## Installation
 
+Install `infctl` command line tool:
 
-# API Reference
+```bash
-
+curl -L https://codeberg.org/headshed/infctl-cli/raw/branch/main/install.sh | bash
-This document provides a reference for the API and CLI usage of the [INFCTL CLI](https://codeberg.org/headshed/infctl-cli) tool 
-
-## PipelineStep Structure
-
-Each pipeline step is defined as:
-
-- `name`: Step name (string)
-- `function`: Function to call (string)
-- `params`: List of parameters (array of strings)
-- `retryCount`: Number of retries (integer)
-- `shouldAbort`: Whether to abort on failure (boolean)
-
-## Available Functions
-
-### k8sNamespaceExists
-Checks if a Kubernetes namespace exists.
-- Params: `[namespace]` (string)
-- Returns: error if namespace does not exist
-
-### RunCommand
-Runs a shell command.
-- Params: `[command]` (string)
-- Returns: error if command fails
-
-## Example Pipeline JSON
-
 ```
-[
+
-  {
+Or download from [Releases](https://codeberg.org/headshed/infctl-cli/releases) and place in your `PATH`.
+
+## Usage
+
+`infctl` uses JSON files for configuration and is designed around pipelines that perform a series of steps.
+
+## Functions
+
+### `k8sNamespaceExists`
+Ensures a Kubernetes namespace exists.
+
+**Parameters:**
+- `namespace` (string) - Name of the namespace
+
+**Example:**
+```json
+{
   "name": "ensure inf namespace exists",
   "function": "k8sNamespaceExists",
   "params": ["infctl"],
   "retryCount": 0,
   "shouldAbort": true
-  },
+}
-  {
+```
-    "name": "create php configmap",
+
+### `RunCommand`
+Executes a shell command, script, or executable.
+
+**Parameters:**
+- `command` (string) - Command, script path, or executable to run
+
+**Examples:**
+```json
+{
+  "name": "run setup script",
   "function": "RunCommand",
   "params": ["./scripts/create_php_configmap_ctl.sh"],
   "retryCount": 0,
   "shouldAbort": true
-  }
+}
-]
 ```
 
-## Notes
+```json
-- Only functions defined in the codebase are available for use in pipelines.
+{
-- The API does not expose any HTTP endpoints; all orchestration is via CLI and pipeline JSON.
+  "name": "say hello",
+  "function": "RunCommand",
+  "params": ["echo 'hello world'"],
+  "retryCount": 0,
+  "shouldAbort": true
+}
+```
+
+## Task Properties
+
+### Required
+- `name` - Human-readable description displayed in logs
+- `function` - Name of function registered within infctl
+- `params` - Array of string parameters passed to the function
+
+### Optional
+- `retryCount` - Number of times to retry if task fails (default: 0)
+- `shouldAbort` - Whether to stop pipeline if task fails (default: true)
+
+## Execution Behavior
+
+- Tasks execute in sequence
+- Task fails if script/command returns non-zero exit code
+- Failed tasks retry up to `retryCount` times
+- If `shouldAbort` is `true` and task fails, pipeline stops
+- If `shouldAbort` is `false`, pipeline continues to next task
+- Unlimited flexibility through `RunCommand` for any automation

src/content/docs/reference/configuration-schema.md

@@ -3,45 +3,10 @@ title: Configuration Schema
 description: JSON schema reference for infctl pipeline configurations.
 ---
 
-# INFCTL CLI Configuration Schema
+## Pipeline Structure
 
+A pipeline is a JSON array of task objects. Each task represents a single operation to be executed in sequence.
 
-# Configuration Schema
-
-This document describes the configuration schema for the [INFCTL CLI](https://codeberg.org/headshed/infctl-cli) tool 
-
-## Base Configuration (`base.json`)
-
-Example:
-```json
-{
-  "retry_delay_seconds": 3
-}
-```
-
-- `retry_delay_seconds` (integer): Delay in seconds before retrying failed steps.
-
-## Project Configuration (`config.json`)
-
-Project configuration fields are defined in the code and may include:
-- Project name
-- Directory paths
-- URLs
-- Port numbers
-- Log format
-
-Refer to the code for exact field names and types.
-
-## Pipeline Configuration (`pipeline.json`)
-
-Pipeline configuration is an array of steps. Each step:
-- `name`: Step name (string)
-- `function`: Function to call (string)
-- `params`: List of parameters (array of strings)
-- `retryCount`: Number of retries (integer)
-- `shouldAbort`: Whether to abort on failure (boolean)
-
-Example:
 ```json
 [
   {
@@ -50,10 +15,122 @@ Example:
     "params": ["infctl"],
     "retryCount": 0,
     "shouldAbort": true
+  },
+  {
+    "name": "create php configmap",
+    "function": "RunCommand",
+    "params": ["./scripts/create_php_configmap_ctl.sh"],
+    "retryCount": 0,
+    "shouldAbort": true
   }
 ]
 ```
 
-## Notes
+## Task Object Schema
-- Example configuration files are provided as `.example` files in the repository.
+
-- All configuration fields must match those defined in the codebase; do not add undocumented fields.
+### Required Properties
+
+#### `name`
+- **Type:** `string`
+- **Description:** Human-readable description displayed in logs
+- **Example:** `"ensure inf namespace exists"`
+
+#### `function`
+- **Type:** `string`
+- **Description:** Name of the function registered within infctl
+- **Known Functions:** `k8sNamespaceExists`, `RunCommand`
+- **Example:** `"RunCommand"`
+
+#### `params`
+- **Type:** `array`
+- **Description:** Array of string parameters passed to the function
+- **Example:** `["./scripts/create_php_configmap_ctl.sh"]`
+
+### Optional Properties
+
+#### `retryCount`
+- **Type:** `number`
+- **Default:** `0`
+- **Description:** Number of times to retry the task if it fails (script returns non-zero)
+- **Example:** `3`
+
+#### `shouldAbort`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Whether to stop the pipeline if this task fails. If `false`, pipeline continues to next task
+- **Example:** `true`
+
+## Known Functions
+
+Based on the documented examples:
+
+#### `k8sNamespaceExists`
+- **Parameters:** `[namespace: string]`
+- **Description:** Ensures a Kubernetes namespace exists
+
+#### `RunCommand`
+- **Parameters:** `[command: string]`
+- **Description:** Executes a shell command, script, or executable
+- **Notes:** Can be any command, script path, or executable. Task fails if command returns non-zero exit code
+
+## Example Configurations
+
+### Basic Two-Step Pipeline
+```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
+  }
+]
+```
+
+### Simple Script Execution
+```json
+[
+  {
+    "name": "say hello",
+    "function": "RunCommand",
+    "params": ["echo 'hello world'"],
+    "retryCount": 0,
+    "shouldAbort": true
+  }
+]
+```
+
+### Continue on Failure
+```json
+[
+  {
+    "name": "optional cleanup",
+    "function": "RunCommand",
+    "params": ["rm -f /tmp/tempfile"],
+    "retryCount": 0,
+    "shouldAbort": false
+  },
+  {
+    "name": "main deployment",
+    "function": "RunCommand",
+    "params": ["./deploy.sh"],
+    "retryCount": 2,
+    "shouldAbort": true
+  }
+]
+```
+
+## Execution Rules
+
+1. **Tasks execute in sequence** - Each task in the array runs one after another
+2. **Failure handling** - If a task fails (returns non-zero), it may be retried up to `retryCount` times
+3. **Pipeline stopping** - If `shouldAbort` is `true` and task fails, pipeline stops. If `false`, pipeline continues
+4. **Unlimited flexibility** - `RunCommand` can execute any script, command, or executable for complete automation flexibility