docs: Update cloud examples with snippets

docs/.gitignore

@@ -0,0 +1,2 @@
+
+site/

docs/docs/cogstack-ce/_index.md

@@ -27,7 +27,7 @@ It combines model serving, de-identification, model training, notebook-based ana
 
 For the full installation reference, deployment instructions, and customizations, see:
 
-- [Deployment](../platform/deployment/_index.md)
+- [Deployment](../platform/deployment/index.md)
 - [CogStack CE Helm chart (install + customization)](../platform/deployment/helm/charts/cogstack-ce-helm.md)
 
 ## Models

docs/docs/cogstack-ce/tutorial/end-to-end-jupyterhub.md

@@ -94,6 +94,6 @@ If those outputs appear, you have validated the full end-to-end flow from Jupyte
 
 ## Next Steps
 
-- See the [full deployment documentation](../../platform/deployment/_index.md) for more details on scaling, production security, and advanced configuration options.
+- See the [full deployment documentation](../../platform/deployment/index.md) for more details on scaling, production security, and advanced configuration options.
 - See full install instructions of the cogstack CE chart[CogStack CE Helm chart (install + customization)](../../platform/deployment/helm/charts/cogstack-ce-helm.md)
 - See further tutorials on medcat on [GitHub](https://github.com/CogStack/cogstack-nlp/tree/79f00cfc204f4ae559b56c8e397bbcaf82d44274/medcat-v2-tutorials)

docs/docs/cogstack-ce/tutorial/quickstart-installation.md

@@ -24,7 +24,7 @@ This command will install Cogstack community edition with all the default values
 
     Once the initial installation is done, then any updates should be significantly faster.
 
-    The defaults are set for a production-ready environment. See [Deployment](../../platform/deployment/_index.md) for detailed deployment information and customization options.
+    The defaults are set for a production-ready environment. See [Deployment](../../platform/deployment/index.md) for detailed deployment information and customization options.
 
 ## Port-forward and open JupyterHub
 

docs/docs/overview/getting-started.md

@@ -20,13 +20,15 @@ Suggested order for reading the docs and getting the most out of CogStack.
 
 **If you care about running CogStack:**
 
-- [Deployment overview](../platform/deployment/_index.md) — Ways to deploy (Helm, Docker Compose, cloud examples).
+- [Deployment overview](../platform/deployment/index.md) — Ways to deploy (Helm, Docker Compose, cloud examples).
 - [Quickstart](../platform/deployment/get-started/quickstart.md) — Get a local instance running quickly.
+- [Deployment examples](../platform/deployment/examples/index.md) — Real-world deployment scenarios for AWS, Azure, OpenStack,
+
 
 ## 3. Deploy and operate
 
 - **[Helm tutorial](../platform/deployment/helm/tutorial.md)** — Deploy with Helm step by step.
-- **[Observability](../platform/observability/_index.md)** — Dashboards, telemetry, and alerting for your deployment.
+- **[Observability](../platform/observability/index.md)** — Dashboards, telemetry, and alerting for your deployment.
 
 ## 4. Go deeper
 

docs/docs/platform/deployment/examples/aws-kubernetes-eks.md

@@ -1,5 +1,13 @@
 # AWS EKS Deployment
 
+<div class="tech-stack-banner" markdown="block">
+
+{{ cogstack_banner_logo() }}
+
+:material-aws:{ .tech-icon-aws } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform }
+
+</div>
+
 This is an example deployment of CogStack in AWS. It will create publically accessible services, so is not suitable for production deployment.
 
 The recommended deployment in AWS is based on using Kubernetes through AWS EKS.
@@ -11,12 +19,29 @@ Deployment through terraform is carried out through two terraform commands, to h
 
 ### Requirements
 - Terraform - [Install Terraform](https://developer.hashicorp.com/terraform/install)
-- AWS Credentials for an account that can create and destroy resources. 
+- AWS Credentials for an account that can create and destroy resources.
+
+### 1. Get the configuration files
+
+All you need to do is get the Terraform files that have been preconfigured for this example (the ZIP contains every `deployment-examples` tree; use the `aws-kubernetes` folder for this guide).
+
+[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button }
+
+Alternatively you can view the file contents here:
+
+#### eks-cluster terraform files
+
+This terraform configuration will create a new AWS EKS cluster.
+
+{{ embed_all_files_in_directory_as_snippets('aws-kubernetes/eks-cluster') }}
+
+#### kubernetes-deployment terraform files
 
+This terraform configuration will use the helm plugin to run services in kubernetes.
 
-### Steps
+{{ embed_all_files_in_directory_as_snippets('aws-kubernetes/kubernetes-deployment') }}
 
-### 1. Add Required Secrets for your env
+### 2. Add required secrets for your environment
 This readme uses environment variables for access:
 
 1. See the `.env.example` file for the required details.
@@ -25,7 +50,7 @@ This readme uses environment variables for access:
 
 If desired, see the official documentation for other ways to provide AWS credentials https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration
 
-### 2. Run Terraform
+### 3. Run Terraform
 Terraform is run on two modules for AWS, so we will run one terraform apply in one folder, then another terraform apply in a second folder. 
 
 Initial provisioning takes around 15 minutes.
@@ -48,7 +73,7 @@ terraform init
 terraform apply --auto-approve
 ```
 
-### 3. Accessing the CogStack Platform
+### 4. Accessing the CogStack Platform
 
 Once the deployment is complete and all services are running, you can access the CogStack platform and its components using the following URLs:
 

docs/docs/platform/deployment/examples/azure-kubernetes-aks.md

@@ -1,20 +1,28 @@
 # Azure AKS Deployment
 
-This is an example deployment of CogStack in Azure. 
+<div class="tech-stack-banner" markdown="block">
+
+{{ cogstack_banner_logo() }}
+
+:material-microsoft-azure:{ .tech-icon-azure } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform }
+
+</div>
+
+This is an example deployment of CogStack in Azure.
 
 The recommended deployment of CogStack in Azure is based on using Kubernetes through Azure Kubernetes Service.
 
-This example will create a AKS cluster, setup any necessary config, deploy CogStack to the cluster, and test that it is available. It will create publically accessible services, so is not suitable for production deployment. 
+This example will create a AKS cluster, setup any necessary config, deploy CogStack to the cluster, and test that it is available. It will create publically accessible services, so is not suitable for production deployment.
 
-We create a cluster following the Official Azure Verified Modules patterns in https://azure.github.io/Azure-Verified-Modules/indexes/terraform/tf-pattern-modules/ to create AKS clusters with their recommended defaults. 
+We create a cluster following the Official Azure Verified Modules patterns in https://azure.github.io/Azure-Verified-Modules/indexes/terraform/tf-pattern-modules/ to create AKS clusters with their recommended defaults.
 
 
 ## Usage
 Deployment through terraform is carried out through two terraform commands, to handle the sequencing issues between making a k8s cluster and using it in the cloud.
 
 ### Requirements
 - Terraform - [Install Terraform](https://developer.hashicorp.com/terraform/install)
-- Azure Credentials for an account and subscription that can create and destroy resources. 
+- Azure Credentials for an account and subscription that can create and destroy resources.
 
 #### Required Permissions
 - Contributor
@@ -23,18 +31,36 @@ Deployment through terraform is carried out through two terraform commands, to h
 #### Required Features
 - EncryptionAtHost: `az feature register --namespace Microsoft.Compute --name EncryptionAtHost`
 
-### Steps
+### 1. Get the configuration files
+
+All you need to do is get the Terraform files that have been preconfigured for this example (this download includes every `deployment-examples` tree; use the `azure-kubernetes` folder for this guide).
+
+[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button }
+
+Alternatively you can view the file contents here:
+
+#### aks-cluster terraform files
 
-### 1. Use the Azure CLI to login for your subscription
-Run the az login command, which will open a web browser for you to login to your azure account. We then set the subscription ID for use by the Azure RM Terraform provider. 
+This terraform configuration will create a new Azure AKS cluster.
+
+{{ embed_all_files_in_directory_as_snippets('azure-kubernetes/aks-cluster') }}
+
+#### kubernetes-deployment terraform files
+
+This terraform configuration will use the helm provider to run services in kubernetes.
+
+{{ embed_all_files_in_directory_as_snippets('azure-kubernetes/kubernetes-deployment') }}
+
+### 2. Use the Azure CLI to login for your subscription
+Run the az login command, which will open a web browser for you to login to your azure account. We then set the subscription ID for use by the Azure RM Terraform provider.
 
 ```bash
 az login
 export ARM_SUBSCRIPTION_ID=$(az account show --query id -o tsv)
 ```
 
-### 2. Run Terraform
-Terraform is run on two modules, so we will run one terraform apply in one folder, then another terraform apply in a second folder. 
+### 3. Run Terraform
+Terraform is run on two modules, so we will run one terraform apply in one folder, then another terraform apply in a second folder.
 
 Initial provisioning takes around 15 minutes.
 
@@ -53,7 +79,7 @@ terraform init
 terraform apply --auto-approve
 ```
 
-### 3. Accessing the CogStack Platform
+### 4. Accessing the CogStack Platform
 
 Once the deployment is complete and all services are running, you can access the CogStack platform and its components using the following URLs:
 
@@ -69,8 +95,6 @@ http://localhost:5000/demo
 
 You can destroy the infra to save costs when it wont be used for a long time.
 
-Do note that there is an initial cost every time the EKS infrastructure is created, looks to be around $0.50 at time of writing.
-
 ```bash
 cd ../kubernetes-deployment
 terraform destroy
@@ -94,7 +118,7 @@ AZURE_KUBECONFIG=$(terraform output -raw kubeconfig_file)
 export KUBECONFIG=${AZURE_KUBECONFIG}
 ```
 
-Note - alternatively you could use the Azure CLI to set your kubeconfig using 
+Note - alternatively you could use the Azure CLI to set your kubeconfig using
 
 ```bash
 MY_RESOURCE_GROUP_NAME=$(terraform output -raw resource_group_name)
@@ -112,4 +136,4 @@ helm install my-medcat oci://registry-1.docker.io/cogstacksystems/medcat-service
 kubectl apply -f resources/ingress-medcat-service.yaml
 # Find public url
 kubectl get ingress
-```
+```

docs/docs/platform/deployment/examples/openstack-docker.md

@@ -1,6 +1,14 @@
 # Openstack Docker Deployment
 
-This Terraform example provides one stop approach to deploy the **CogStack** platform with its core components and observability stack in an OpenStack environment. It is specifically designed to simplify and automate the provisioning and configuration needed to run CogStack reliably and securely. 
+<div class="tech-stack-banner" markdown="block">
+
+{{ cogstack_banner_logo() }}
+
+:simple-openstack:{ .tech-icon-openstack } :simple-docker:{ .tech-icon-docker } :simple-portainer: :simple-ansible:{ .tech-icon-ansible } :simple-terraform:{ .tech-icon-terraform }
+
+</div>
+
+This Terraform example provides one stop approach to deploy the **CogStack** platform with its core components and observability stack in an OpenStack environment. It is specifically designed to simplify and automate the provisioning and configuration needed to run CogStack reliably and securely.
 
 This example:
 
@@ -17,11 +25,31 @@ This example:
 - Terraform - [Install Terraform](https://developer.hashicorp.com/terraform/install)
 - Openstack Cloud environment
 
-### 1. Add Required Secrets for your env
+### 1. Get the configuration files
+
+Get the Terraform files for this example (the ZIP contains all `deployment-examples`; use the `openstack-docker` folder for this guide).
+
+[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button }
+
+Alternatively you can view the file contents here:
+
+#### openstack-vms terraform files
+
+This module provisions OpenStack VMs and networking for the stack.
+
+{{ embed_all_files_in_directory_as_snippets('openstack-docker/openstack-vms') }}
+
+#### docker-deployment terraform files
+
+This module deploys Docker-based CogStack services.
+
+{{ embed_all_files_in_directory_as_snippets('openstack-docker/docker-deployment') }}
+
+### 2. Add required secrets for your environment
 
-Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment. 
+Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment.
 
-### 2. Run Terraform
+### 3. Run Terraform
 
 ```bash
 terraform init
@@ -30,7 +58,7 @@ terraform apply
 
 Initial provisioning takes up to 10 minutes, where time is mostly downloading large docker images
 
-### 3. Accessing the CogStack Platform
+### 4. Accessing the CogStack Platform
 
 Once the deployment is complete and all services are running, you can access the CogStack platform and its components using the following URLs:
 

docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md

@@ -1,6 +1,14 @@
 # Openstack Kubernetes Deployment
 
-This Terraform example provides one stop approach to deploy the **CogStack** platform with its core components and observability stack in an OpenStack environment. It is specifically designed to simplify and automate the provisioning and configuration needed to run CogStack reliably and securely. 
+<div class="tech-stack-banner" markdown="block">
+
+{{ cogstack_banner_logo() }}
+
+:simple-openstack:{ .tech-icon-openstack } :simple-docker:{ .tech-icon-docker } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform }
+
+</div>
+
+This Terraform example provides one stop approach to deploy the **CogStack** platform with its core components and observability stack in an OpenStack environment. It is specifically designed to simplify and automate the provisioning and configuration needed to run CogStack reliably and securely.
 
 This example:
 
@@ -14,14 +22,33 @@ This example:
 - Terraform - [Install Terraform](https://developer.hashicorp.com/terraform/install)
 - Openstack Cloud environment
 
-### 1. Add Required Secrets for your env
+### 1. Get the configuration files
+
+Get the Terraform files for this example (the ZIP contains all `deployment-examples`; use the `openstack-kubernetes` folder for this guide).
+
+[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button }
+
+Alternatively you can view the file contents here:
+
+#### k3s-cluster terraform files
 
-Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment. 
+This terraform configuration provisions VMs and installs k3s.
 
-### 2. Run Terraform
+{{ embed_all_files_in_directory_as_snippets('openstack-kubernetes/k3s-cluster') }}
+
+#### kubernetes-deployment terraform files
+
+This terraform configuration deploys CogStack services to the cluster.
+
+{{ embed_all_files_in_directory_as_snippets('openstack-kubernetes/kubernetes-deployment') }}
+
+### 2. Add required secrets for your environment
+
+Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment.
+
+### 3. Run Terraform
 
 ```bash
-# Create AKS cluster
 cd k3s-cluster
 terraform init
 terraform apply --auto-approve
@@ -37,7 +64,7 @@ terraform apply --auto-approve
 
 Initial provisioning takes up to 10 minutes, where time is mostly downloading large docker images
 
-### 3. Accessing the CogStack Platform
+### 4. Accessing the CogStack Platform
 
 Once the deployment is complete and all services are running, you can access the CogStack platform and its components using the following URLs:
 
@@ -72,4 +99,4 @@ Access the k8s dashboard using
 ```
 terraform output dashboard # Find the access token
 kubectl -n kubernetes-dashboard port-forward svc/kubernetes-dashboard-kong-proxy 8443:443
-```
+```

docs/docs/platform/deployment/helm/charts/_index.md → docs/docs/platform/deployment/helm/charts/index.md

@@ -6,7 +6,7 @@
 - [MedCAT Service Helm](medcat-service-helm.md)
 - [MedCAT Trainer Helm](medcat-trainer-helm.md)
 - [CogStack Community Edition Helm](cogstack-ce-helm.md)
-- [CogStack Observability Helm](cogstack-observability-helm.md.md)
+- [CogStack Observability Helm](cogstack-observability-helm.md)
 
 ## Chart Publishing
 

docs/docs/platform/deployment/helm/_index.md → docs/docs/platform/deployment/helm/index.md

@@ -5,6 +5,6 @@ Helm is our recommended way to deploy CogStack. It simplifies installing, upgrad
 
 For a detailed, step-by-step walkthrough on deploying CogStack with Helm, please see the [Tutorial](./tutorial.md).
 
-To understand how the Helm charts are structured and how they work under the hood, check out the [Charts](./charts/_index.md) section.
+To understand how the Helm charts are structured and how they work under the hood, check out the [Charts](./charts/index.md) section.