From 1af6a7ff90263fd1812c1072876986e66cfce85e Mon Sep 17 00:00:00 2001 From: alhendrickson Date: Thu, 7 May 2026 12:59:48 +0000 Subject: [PATCH 1/5] docs: Update cloud examples with snippets --- docs/.gitignore | 2 + .../deployment/examples/aws-kubernetes-eks.md | 27 +++++-- docs/docs/stylesheets/extra.css | 13 ++++ docs/main.py | 76 +++++++++++++++++++ docs/mkdocs.yml | 13 ++++ docs/pyproject.toml | 1 + docs/scripts/zip_deployment_examples.py | 56 ++++++++++++++ docs/uv.lock | 53 +++++++++++++ 8 files changed, 236 insertions(+), 5 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/docs/stylesheets/extra.css create mode 100644 docs/main.py create mode 100644 docs/scripts/zip_deployment_examples.py diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..91fe08f --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ + +site/ diff --git a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md index ae17bc3..67236bd 100644 --- a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md +++ b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md @@ -11,12 +11,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 -### Steps +All you need to do is get the few terraform files that have been preconfigured for this example. -### 1. Add Required Secrets for your env +[Download all Terraform sources for this example](../../../assets/downloads/deployment-examples-aws-kubernetes.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. + +{{ embed_all_files_in_directory_as_snippets('aws-kubernetes/kubernetes-deployment') }} + +### 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 +42,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 +65,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: diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css new file mode 100644 index 0000000..4ef050f --- /dev/null +++ b/docs/docs/stylesheets/extra.css @@ -0,0 +1,13 @@ +/* + * Long fenced code blocks (including content pulled in via pymdownx.snippets) + * stay within a capped height; scroll vertically inside the block. + * Tweak --md-code-block-max-height as needed (Material uses CSS variables elsewhere). + */ +:root { + --md-code-block-max-height: min(70vh, 28rem); +} + +.md-typeset .highlight pre { + max-height: var(--md-code-block-max-height); + overflow-y: auto; +} diff --git a/docs/main.py b/docs/main.py new file mode 100644 index 0000000..74acab7 --- /dev/null +++ b/docs/main.py @@ -0,0 +1,76 @@ +"""MkDocs-Macros definitions (see https://mkdocs-macros-plugin.readthedocs.io/).""" + +from __future__ import annotations + +from fnmatch import fnmatch +from pathlib import Path + + +def define_env(env): + """Register Jinja macros available as {{ macro_name(...) }} in Markdown.""" + + repo_root = Path(__file__).resolve().parent.parent + + @env.macro + def embed_all_files_in_directory_as_snippets( + folder: str, + patterns: str = "*.tf,*.hcl,*.yml,*.yaml", + ) -> str: + """ + Emit pymdownx **tabbed** blocks with **snippets** for every matching file under a directory. + + ``folder`` is relative to the repo ``deployment-examples/`` directory. Snippet paths match + that layout; ensure ``pymdownx.snippets`` ``base_path`` includes ``../deployment-examples``. + + ``patterns`` is a comma-separated list of globs matched against the **basename** + (e.g. ``*.tf`` or ``*`` for every file). Hidden files (names starting with ``.``) are skipped. + """ + root = repo_root / "deployment-examples" / folder + if not root.is_dir(): + raise FileNotFoundError( + f"embed_all_files_in_directory_as_snippets: not a directory: {root}" + ) + + globs = [p.strip() for p in patterns.split(",") if p.strip()] + if not globs: + globs = ["*"] + + def include_file(path: Path) -> bool: + if path.name.startswith("."): + return False + return any(fnmatch(path.name, g) for g in globs) + + paths = sorted( + (p for p in root.rglob("*") if p.is_file() and include_file(p)), + key=lambda p: p.as_posix(), + ) + if not paths: + return "_No matching files found._" + + blocks: list[str] = [] + deploy_root = repo_root / "deployment-examples" + for path in paths: + rel = path.relative_to(deploy_root).as_posix() + title = path.relative_to(root).as_posix() + language = _fence_language(path.suffix) + inner_indent = " " + blocks.append(f'=== "{title}"') + blocks.append(f"{inner_indent}```{language}") + blocks.append(f'{inner_indent}--8<-- "{rel}"') + blocks.append(f"{inner_indent}```") + blocks.append("") + + return "\n".join(blocks).rstrip() + "\n" + + +def _fence_language(suffix: str) -> str: + return { + ".tf": "hcl", + ".hcl": "hcl", + ".yml": "yaml", + ".yaml": "yaml", + ".json": "json", + ".md": "markdown", + ".sh": "bash", + ".txt": "text", + }.get(suffix.lower(), "text") diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index eceeb7a..84bdfcb 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -105,10 +105,12 @@ nav: plugins: - search + - macros - gen-files: scripts: - scripts/gen_helm_readme.py - scripts/copy_files_from_repo.py + - scripts/zip_deployment_examples.py - termynal - mkdocs-jupyter: ignore_h1_titles: True @@ -117,11 +119,22 @@ extra: analytics: provider: custom +extra_css: + - stylesheets/extra.css + markdown_extensions: - admonition - attr_list - pymdownx.details - pymdownx.superfences + - pymdownx.snippets: + check_paths: true + base_path: + - docs + # Include the deployment-examples dir to embed the terraform files + - ../deployment-examples + - pymdownx.tabbed: + alternate_style: true - pymdownx.emoji: emoji_index: !!python/name:material.extensions.emoji.twemoji emoji_generator: !!python/name:material.extensions.emoji.to_svg diff --git a/docs/pyproject.toml b/docs/pyproject.toml index b1d5f5f..111d446 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -5,6 +5,7 @@ description = "CogStack Documentation" readme = "README.md" requires-python = ">=3.10" dependencies = [ + "mkdocs-macros-plugin>=1.3.0", "mkdocs-gen-files>=0.6.1", "mkdocs-jupyter>=0.26.1", "mkdocs-material>=9.7.0", diff --git a/docs/scripts/zip_deployment_examples.py b/docs/scripts/zip_deployment_examples.py new file mode 100644 index 0000000..0dcb8ed --- /dev/null +++ b/docs/scripts/zip_deployment_examples.py @@ -0,0 +1,56 @@ +from __future__ import annotations + +""" +mkdocs-gen-files generator: zip archives of deployment example folders. + +Each zip is written under `docs_dir` so MkDocs publishes it as a static download. + +Configuration: +`ZIP_SPECS` is a list of dicts with: +- `sourceFolderPath`: directory under the repository root to archive (recursive) +- `outputZipPath`: path (relative to MkDocs `docs_dir`) for the `.zip` file +""" + +import io +import zipfile +from pathlib import Path + +import mkdocs_gen_files # type: ignore[import-not-found] + + +REPO_ROOT = Path(__file__).resolve().parents[2] + +ZIP_SPECS = [ + { + "sourceFolderPath": "deployment-examples/aws-kubernetes", + "outputZipPath": "assets/downloads/deployment-examples-aws-kubernetes.zip", + }, +] + + +def main() -> None: + """Build configured zips and register them with the MkDocs virtual file tree.""" + for spec in ZIP_SPECS: + source_rel = spec["sourceFolderPath"] + output_rel = spec["outputZipPath"] + + source_dir = REPO_ROOT / source_rel + if not source_dir.is_dir(): + raise FileNotFoundError(f"Source directory not found: {source_dir}") + + root_name = source_dir.name + buf = io.BytesIO() + with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf: + for path in sorted(source_dir.rglob("*"), key=lambda p: p.as_posix()): + if not path.is_file(): + continue + arcname = Path(root_name) / path.relative_to(source_dir) + zf.write(path, arcname.as_posix()) + + out = Path(output_rel) + with mkdocs_gen_files.open(out.as_posix(), "wb") as f: + f.write(buf.getvalue()) + mkdocs_gen_files.set_edit_path(out.as_posix(), source_dir.relative_to(REPO_ROOT)) + + +main() diff --git a/docs/uv.lock b/docs/uv.lock index 0f4b9d1..5d94c77 100644 --- a/docs/uv.lock +++ b/docs/uv.lock @@ -286,6 +286,7 @@ source = { virtual = "." } dependencies = [ { name = "mkdocs-gen-files" }, { name = "mkdocs-jupyter" }, + { name = "mkdocs-macros-plugin" }, { name = "mkdocs-material" }, { name = "termynal" }, ] @@ -299,6 +300,7 @@ dev = [ requires-dist = [ { name = "mkdocs-gen-files", specifier = ">=0.6.1" }, { name = "mkdocs-jupyter", specifier = ">=0.26.1" }, + { name = "mkdocs-macros-plugin", specifier = ">=1.3.0" }, { name = "mkdocs-material", specifier = ">=9.7.0" }, { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.12.11" }, { name = "termynal", specifier = ">=0.13.1" }, @@ -412,6 +414,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl", hash = "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", size = 11034, upload-time = "2022-05-02T15:47:14.552Z" }, ] +[[package]] +name = "hjson" +version = "3.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/82/e5/0b56d723a76ca67abadbf7fb71609fb0ea7e6926e94fcca6c65a85b36a0e/hjson-3.1.0.tar.gz", hash = "sha256:55af475a27cf83a7969c808399d7bccdec8fb836a07ddbd574587593b9cdcf75", size = 40541, upload-time = "2022-08-13T02:53:01.919Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1f/7f/13cd798d180af4bf4c0ceddeefba2b864a63c71645abc0308b768d67bb81/hjson-3.1.0-py3-none-any.whl", hash = "sha256:65713cdcf13214fb554eb8b4ef803419733f4f5e551047c9b711098ab7186b89", size = 54018, upload-time = "2022-08-13T02:52:59.899Z" }, +] + [[package]] name = "idna" version = "3.11" @@ -867,6 +878,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/93/89/eb601278b12c471235860992f5973cf3c55ca3f77d1d6127389eb045a021/mkdocs_jupyter-0.26.1-py3-none-any.whl", hash = "sha256:527242c2c8f1d30970764bbab752de41243e5703f458d8bc05336ec53828192e", size = 1459618, upload-time = "2026-03-24T15:32:46.25Z" }, ] +[[package]] +name = "mkdocs-macros-plugin" +version = "1.5.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "hjson" }, + { name = "jinja2" }, + { name = "mkdocs" }, + { name = "packaging" }, + { name = "pathspec" }, + { name = "python-dateutil" }, + { name = "pyyaml" }, + { name = "requests" }, + { name = "super-collections" }, + { name = "termcolor" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/92/15/e6a44839841ebc9c5872fa0e6fad1c3757424e4fe026093b68e9f386d136/mkdocs_macros_plugin-1.5.0.tar.gz", hash = "sha256:12aa45ce7ecb7a445c66b9f649f3dd05e9b92e8af6bc65e4acd91d26f878c01f", size = 37730, upload-time = "2025-11-13T08:08:55.545Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/51/62/9fffba5bb9ed3d31a932ad35038ba9483d59850256ee0fea7f1187173983/mkdocs_macros_plugin-1.5.0-py3-none-any.whl", hash = "sha256:c10fabd812bf50f9170609d0ed518e54f1f0e12c334ac29141723a83c881dd6f", size = 44626, upload-time = "2025-11-13T08:08:53.878Z" }, +] + [[package]] name = "mkdocs-material" version = "9.7.1" @@ -1509,6 +1541,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f1/7b/ce1eafaf1a76852e2ec9b22edecf1daa58175c090266e9f6c64afcd81d91/stack_data-0.6.3-py3-none-any.whl", hash = "sha256:d5558e0c25a4cb0853cddad3d77da9891a08cb85dd9f9f91b9f8cd66e511e695", size = 24521, upload-time = "2023-09-30T13:58:03.53Z" }, ] +[[package]] +name = "super-collections" +version = "0.6.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "hjson" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/e0/de/a0c3d1244912c260638f0f925e190e493ccea37ecaea9bbad7c14413b803/super_collections-0.6.2.tar.gz", hash = "sha256:0c8d8abacd9fad2c7c1c715f036c29f5db213f8cac65f24d45ecba12b4da187a", size = 31315, upload-time = "2025-09-30T00:37:08.067Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/17/43/47c7cf84b3bd74a8631b02d47db356656bb8dff6f2e61a4c749963814d0d/super_collections-0.6.2-py3-none-any.whl", hash = "sha256:291b74d26299e9051d69ad9d89e61b07b6646f86a57a2f5ab3063d206eee9c56", size = 16173, upload-time = "2025-09-30T00:37:07.104Z" }, +] + +[[package]] +name = "termcolor" +version = "3.3.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/46/79/cf31d7a93a8fdc6aa0fbb665be84426a8c5a557d9240b6239e9e11e35fc5/termcolor-3.3.0.tar.gz", hash = "sha256:348871ca648ec6a9a983a13ab626c0acce02f515b9e1983332b17af7979521c5", size = 14434, upload-time = "2025-12-29T12:55:21.882Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/33/d1/8bb87d21e9aeb323cc03034f5eaf2c8f69841e40e4853c2627edf8111ed3/termcolor-3.3.0-py3-none-any.whl", hash = "sha256:cf642efadaf0a8ebbbf4bc7a31cec2f9b5f21a9f726f4ccbb08192c9c26f43a5", size = 7734, upload-time = "2025-12-29T12:55:20.718Z" }, +] + [[package]] name = "termynal" version = "0.13.1" From 81597d64300378b7d59f1b85b44415dc380cbcf0 Mon Sep 17 00:00:00 2001 From: alhendrickson Date: Thu, 7 May 2026 13:17:26 +0000 Subject: [PATCH 2/5] docs(deployment): Embed all the deployment TF files as snippets --- docs/docs/platform/deployment/_index.md | 2 +- .../deployment/examples/aws-kubernetes-eks.md | 4 +- .../examples/azure-kubernetes-aks.md | 44 +++++++++++++------ .../examples/{_index.md => index.md} | 0 .../deployment/examples/openstack-docker.md | 30 ++++++++++--- .../examples/openstack-kubernetes-k3s.md | 33 +++++++++++--- docs/mkdocs.yml | 2 +- docs/scripts/zip_deployment_examples.py | 6 +-- 8 files changed, 88 insertions(+), 33 deletions(-) rename docs/docs/platform/deployment/examples/{_index.md => index.md} (100%) diff --git a/docs/docs/platform/deployment/_index.md b/docs/docs/platform/deployment/_index.md index 5b054b2..522727b 100644 --- a/docs/docs/platform/deployment/_index.md +++ b/docs/docs/platform/deployment/_index.md @@ -17,7 +17,7 @@ If you want to get started quickly, check out the [Quickstart](./get-started/qui Our recommended deployment method is on Kubernetes using Helm charts. This makes installing and managing CogStack easy and consistent. For a detailed walkthrough, see [Helm](./helm/_index.md). -You can run Kubernetes anywhere — on your own hardware or through cloud providers like AWS (EKS) or Azure (AKS). To help with this, we provide basic examples using Terraform that will deploy the infrastructure, services, and perform tests using a few terraform commands. These are available in the [Examples](./examples/_index.md) section. +You can run Kubernetes anywhere — on your own hardware or through cloud providers like AWS (EKS) or Azure (AKS). To help with this, we provide basic examples using Terraform that will deploy the infrastructure, services, and perform tests using a few terraform commands. These are available in the [Examples](./examples/index.md) section. Along with kubernetes, it is also possible to run CogStack through docker compose. See the [Docker Compose](./reference/docker-compose/_index.md) section for this. diff --git a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md index 67236bd..8ac0115 100644 --- a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md +++ b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md @@ -15,9 +15,9 @@ Deployment through terraform is carried out through two terraform commands, to h ### 1. Get the configuration files -All you need to do is get the few terraform files that have been preconfigured for this example. +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 Terraform sources for this example](../../../assets/downloads/deployment-examples-aws-kubernetes.zip){ .md-button } +[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button } Alternatively you can view the file contents here: diff --git a/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md b/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md index 83a2212..8482891 100644 --- a/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md +++ b/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md @@ -1,12 +1,12 @@ # Azure AKS Deployment -This is an example deployment of CogStack in Azure. +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 @@ -14,7 +14,7 @@ Deployment through terraform is carried out through two terraform commands, to h ### 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 +23,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 -### 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. +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 + +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 +71,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 +87,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 +110,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 +128,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 -``` \ No newline at end of file +``` diff --git a/docs/docs/platform/deployment/examples/_index.md b/docs/docs/platform/deployment/examples/index.md similarity index 100% rename from docs/docs/platform/deployment/examples/_index.md rename to docs/docs/platform/deployment/examples/index.md diff --git a/docs/docs/platform/deployment/examples/openstack-docker.md b/docs/docs/platform/deployment/examples/openstack-docker.md index 090c545..7af5198 100644 --- a/docs/docs/platform/deployment/examples/openstack-docker.md +++ b/docs/docs/platform/deployment/examples/openstack-docker.md @@ -1,6 +1,6 @@ # 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. +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 +17,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 -Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment. +Get the Terraform files for this example (the ZIP contains all `deployment-examples`; use the `openstack-docker` folder for this guide). -### 2. Run Terraform +[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. + +### 3. Run Terraform ```bash terraform init @@ -30,7 +50,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: diff --git a/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md b/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md index 311a539..7ede1e0 100644 --- a/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md +++ b/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md @@ -1,6 +1,6 @@ # 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. +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 +14,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 -Create a `terraform.tfvars` file, based on `terraform.tfvars.example`, containing the secrets for your environment. +Get the Terraform files for this example (the ZIP contains all `deployment-examples`; use the `openstack-kubernetes` folder for this guide). -### 2. Run Terraform +[Download all deployment examples (ZIP)](../../../assets/downloads/deployment-examples.zip){ .md-button } + +Alternatively you can view the file contents here: + +#### k3s-cluster terraform files + +This terraform configuration provisions VMs and installs k3s. + +{{ 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 +56,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 +91,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 -``` \ No newline at end of file +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 84bdfcb..28f57ef 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -75,7 +75,7 @@ nav: - Cogstack Observability Helm: platform/deployment/helm/charts/cogstack-observability-helm.md - Cogstack JupyterHub Helm: platform/deployment/helm/charts/cogstack-jupyterhub-helm.md - Examples: - - Examples: platform/deployment/examples/_index.md + - Examples: platform/deployment/examples/index.md - AWS Kubernetes EKS: platform/deployment/examples/aws-kubernetes-eks.md - Azure Kubernetes AKS: platform/deployment/examples/azure-kubernetes-aks.md - OpenStack Kubernetes K3s: platform/deployment/examples/openstack-kubernetes-k3s.md diff --git a/docs/scripts/zip_deployment_examples.py b/docs/scripts/zip_deployment_examples.py index 0dcb8ed..044bc9d 100644 --- a/docs/scripts/zip_deployment_examples.py +++ b/docs/scripts/zip_deployment_examples.py @@ -1,7 +1,7 @@ from __future__ import annotations """ -mkdocs-gen-files generator: zip archives of deployment example folders. +mkdocs-gen-files generator: zip archives from repository folders. Each zip is written under `docs_dir` so MkDocs publishes it as a static download. @@ -22,8 +22,8 @@ ZIP_SPECS = [ { - "sourceFolderPath": "deployment-examples/aws-kubernetes", - "outputZipPath": "assets/downloads/deployment-examples-aws-kubernetes.zip", + "sourceFolderPath": "deployment-examples", + "outputZipPath": "assets/downloads/deployment-examples.zip", }, ] From 0a47fc9963fbb40328a3d30e69521b2f56a3cf14 Mon Sep 17 00:00:00 2001 From: alhendrickson Date: Thu, 7 May 2026 13:23:15 +0000 Subject: [PATCH 3/5] docs(deployment): Embed all the deployment TF files as snippets - fix rtd --- docs/mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 28f57ef..530e20e 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -131,8 +131,9 @@ markdown_extensions: check_paths: true base_path: - docs - # Include the deployment-examples dir to embed the terraform files + # Repo root (e.g. Read the Docs) vs. docs/ project dir (local `cd docs && mkdocs`) - ../deployment-examples + - deployment-examples - pymdownx.tabbed: alternate_style: true - pymdownx.emoji: From 395426226e0055ba6d1f92501e83dfb508b875ce Mon Sep 17 00:00:00 2001 From: alhendrickson Date: Thu, 7 May 2026 14:00:33 +0000 Subject: [PATCH 4/5] docs: Add icons for deployment examples --- .../deployment/examples/aws-kubernetes-eks.md | 8 ++ .../examples/azure-kubernetes-aks.md | 8 ++ .../deployment/examples/openstack-docker.md | 8 ++ .../examples/openstack-kubernetes-k3s.md | 8 ++ docs/docs/stylesheets/extra.css | 85 +++++++++++++++++++ docs/main.py | 12 +++ docs/mkdocs.yml | 1 + 7 files changed, 130 insertions(+) diff --git a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md index 8ac0115..9b5bea7 100644 --- a/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md +++ b/docs/docs/platform/deployment/examples/aws-kubernetes-eks.md @@ -1,5 +1,13 @@ # AWS EKS Deployment +
+ +{{ cogstack_banner_logo() }} + +:material-aws:{ .tech-icon-aws } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform } + +
+ 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. diff --git a/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md b/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md index 8482891..9d7ee17 100644 --- a/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md +++ b/docs/docs/platform/deployment/examples/azure-kubernetes-aks.md @@ -1,5 +1,13 @@ # Azure AKS Deployment +
+ +{{ cogstack_banner_logo() }} + +:material-microsoft-azure:{ .tech-icon-azure } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform } + +
+ 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. diff --git a/docs/docs/platform/deployment/examples/openstack-docker.md b/docs/docs/platform/deployment/examples/openstack-docker.md index 7af5198..d1a2ec7 100644 --- a/docs/docs/platform/deployment/examples/openstack-docker.md +++ b/docs/docs/platform/deployment/examples/openstack-docker.md @@ -1,5 +1,13 @@ # Openstack Docker Deployment +
+ +{{ 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 } + +
+ 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: diff --git a/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md b/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md index 7ede1e0..fe513e9 100644 --- a/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md +++ b/docs/docs/platform/deployment/examples/openstack-kubernetes-k3s.md @@ -1,5 +1,13 @@ # Openstack Kubernetes Deployment +
+ +{{ cogstack_banner_logo() }} + +:simple-openstack:{ .tech-icon-openstack } :simple-docker:{ .tech-icon-docker } :simple-kubernetes:{ .tech-icon-kubernetes } :simple-terraform:{ .tech-icon-terraform } + +
+ 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: diff --git a/docs/docs/stylesheets/extra.css b/docs/docs/stylesheets/extra.css index 4ef050f..ffdc61e 100644 --- a/docs/docs/stylesheets/extra.css +++ b/docs/docs/stylesheets/extra.css @@ -11,3 +11,88 @@ max-height: var(--md-code-block-max-height); overflow-y: auto; } + +/* Large technology icons row (use with md_in_html wrapper, see deployment examples) */ +.md-typeset .tech-stack-banner { + display: inline-flex; + flex-wrap: wrap; + align-items: center; + gap: 1.25rem; + padding: 1rem 1.25rem; + margin: 0 0 1.25rem; + max-width: 100%; + box-sizing: border-box; + border-radius: 0.2rem; + border: 1px solid var(--md-default-fg-color--lightest); + background-color: var(--md-code-bg-color); +} + +/* Markdown wraps banner content in

; flatten so flex aligns logo + icons */ +.md-typeset .tech-stack-banner > p { + display: contents; + margin: 0; +} + +.md-typeset .tech-stack-banner .twemoji { + width: var(--tech-banner-icon-size, 2.75rem); + height: var(--tech-banner-icon-size, 2.75rem); + display: inline-flex; + align-items: center; + justify-content: center; +} + +.md-typeset .tech-stack-banner .twemoji img, +.md-typeset .tech-stack-banner .twemoji svg { + width: 100%; + height: 100%; +} + +.md-typeset .tech-stack-banner .tech-stack-banner__logo-svg { + display: inline-flex; + align-items: center; + flex-shrink: 0; + height: var(--tech-banner-icon-size, 2.75rem); +} + +.md-typeset .tech-stack-banner .tech-stack-banner__logo-svg svg { + height: 100%; + width: auto; + max-width: 9rem; + display: block; +} + +/* Brand colours — use { .tech-icon-* } on each shortcode in the banner */ +.md-typeset .tech-stack-banner .twemoji.tech-icon-aws svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-aws svg { + fill: #ff9900 !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-kubernetes svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-kubernetes svg { + fill: #326ce5 !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-terraform svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-terraform svg { + fill: #844fba !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-azure svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-azure svg { + fill: #0078d4 !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-openstack svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-openstack svg { + fill: #da1a32 !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-docker svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-docker svg { + fill: #2496ed !important; +} + +.md-typeset .tech-stack-banner .twemoji.tech-icon-ansible svg *, +.md-typeset .tech-stack-banner .twemoji.tech-icon-ansible svg { + fill: #000000 !important; +} diff --git a/docs/main.py b/docs/main.py index 74acab7..962965a 100644 --- a/docs/main.py +++ b/docs/main.py @@ -11,6 +11,18 @@ def define_env(env): repo_root = Path(__file__).resolve().parent.parent + @env.macro + def cogstack_banner_logo() -> str: + """Inline SVG for the tech-stack banner (avoids late fetch vs emoji icons).""" + docs_dir = Path(env.conf.docs_dir) + path = docs_dir / "assets" / "brand-logo-dark.svg" + svg = path.read_text(encoding="utf-8").strip() + if svg.startswith("", 1)[-1].strip() + return ( + f'{svg}' + ) + @env.macro def embed_all_files_in_directory_as_snippets( folder: str, diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 530e20e..97d2e55 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -123,6 +123,7 @@ extra_css: - stylesheets/extra.css markdown_extensions: + - md_in_html - admonition - attr_list - pymdownx.details From 1c7038b4228cd6bf37470dd95e8025c9a72023fc Mon Sep 17 00:00:00 2001 From: alhendrickson Date: Thu, 7 May 2026 14:12:59 +0000 Subject: [PATCH 5/5] docs: Rename _index to index to fix sections --- docs/docs/cogstack-ce/_index.md | 2 +- .../tutorial/end-to-end-jupyterhub.md | 2 +- .../tutorial/quickstart-installation.md | 2 +- docs/docs/overview/getting-started.md | 6 ++-- .../helm/charts/{_index.md => index.md} | 2 +- .../deployment/helm/cogstack-helm-module.md | 29 ------------------- .../deployment/helm/{_index.md => index.md} | 2 +- .../docs/platform/deployment/helm/tutorial.md | 7 ----- .../deployment/{_index.md => index.md} | 2 +- docs/docs/platform/index.md | 4 +-- .../observability/{_index.md => index.md} | 0 docs/mkdocs.yml | 12 ++++---- 12 files changed, 17 insertions(+), 53 deletions(-) rename docs/docs/platform/deployment/helm/charts/{_index.md => index.md} (87%) delete mode 100644 docs/docs/platform/deployment/helm/cogstack-helm-module.md rename docs/docs/platform/deployment/helm/{_index.md => index.md} (82%) rename docs/docs/platform/deployment/{_index.md => index.md} (95%) rename docs/docs/platform/observability/{_index.md => index.md} (100%) diff --git a/docs/docs/cogstack-ce/_index.md b/docs/docs/cogstack-ce/_index.md index 892c14e..999bb67 100644 --- a/docs/docs/cogstack-ce/_index.md +++ b/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 diff --git a/docs/docs/cogstack-ce/tutorial/end-to-end-jupyterhub.md b/docs/docs/cogstack-ce/tutorial/end-to-end-jupyterhub.md index f0b53f2..cc839e1 100644 --- a/docs/docs/cogstack-ce/tutorial/end-to-end-jupyterhub.md +++ b/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) diff --git a/docs/docs/cogstack-ce/tutorial/quickstart-installation.md b/docs/docs/cogstack-ce/tutorial/quickstart-installation.md index 95cc1b3..9e13234 100644 --- a/docs/docs/cogstack-ce/tutorial/quickstart-installation.md +++ b/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 diff --git a/docs/docs/overview/getting-started.md b/docs/docs/overview/getting-started.md index 324ce29..250e989 100644 --- a/docs/docs/overview/getting-started.md +++ b/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 diff --git a/docs/docs/platform/deployment/helm/charts/_index.md b/docs/docs/platform/deployment/helm/charts/index.md similarity index 87% rename from docs/docs/platform/deployment/helm/charts/_index.md rename to docs/docs/platform/deployment/helm/charts/index.md index e505c02..62d1d9f 100644 --- a/docs/docs/platform/deployment/helm/charts/_index.md +++ b/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 diff --git a/docs/docs/platform/deployment/helm/cogstack-helm-module.md b/docs/docs/platform/deployment/helm/cogstack-helm-module.md deleted file mode 100644 index 98798ad..0000000 --- a/docs/docs/platform/deployment/helm/cogstack-helm-module.md +++ /dev/null @@ -1,29 +0,0 @@ - -# CogStack Helm Terraform Module -This Terraform module deploys CogStack services using Helm charts on a Kubernetes cluster. - -## Example usage - -```hcl -module "cogstack_helm_services" { - source = "path_to_module" - medcat_service_values = <