docs: document demos' commands

.vscode/settings.json

@@ -1,7 +1,8 @@
 {
-  "cSpell.words": [
-    "cdevents",
-    "cdviz",
-    "sdlc"
-  ],
+  "cSpell.words": ["cdevents", "cdviz", "sdlc"],
+  "languageToolLinter.languageTool.ignoredWordsInWorkspace": [
+    "adminer",
+    "cloudnativepg",
+    "kubewatch"
+  ]
 }

demos/.mise.toml

@@ -10,9 +10,11 @@ kind = "0.26.0"                                                       # to have
 "ubi:helmwave/helmwave" = { version = "0.41", matching = "helmwave" }
 
 [tasks."clean"]
-run = ["mise run stack:compose:clean"]
+description = "Clean / Delete every stacks"
+depends = ["stack:*:delete"]
 
 [tasks."stack:compose:up"]
+description = "Launch the docker compose demo (in foreground)"
 dir = "stack-compose"
 run = [
     "mkdir -p tmp/postgres/data || true",
@@ -21,10 +23,12 @@ run = [
 ]
 
 [tasks."stack:compose:down"]
+description = "Stop the docker compose demo"
 dir = "stack-compose"
 run = ["docker compose -f docker-compose.yaml stop"]
 
-[tasks."stack:compose:clean"]
+[tasks."stack:compose:delete"]
+description = "Stop & remove the docker compose demo (and local data)"
 dir = "stack-compose"
 run = [
     "mise run stack:compose:down",
@@ -33,12 +37,15 @@ run = [
 ]
 
 [tasks."stack:grafana:view"]
+description = "Open the Grafana dashboard (compose demo, k8s demo (after port-forward))"
 run = ["open http://127.0.0.1:3000"]
 
 [tasks."stack:db-admin:view"]
+description = "Open the db-admin UI, adminer (compose demo)"
 run = ["open http://127.0.0.1:5499"]
 
 [tasks."example_01:run"]
+description = "Launch cdviz-collector cli with content (data & configuration) of the example_01 folder"
 dir = "example_01"
 env = { OTEL_TRACES_SAMPLER = "always_off", OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = "http://127.0.0.1:4317", CDVIZ_COLLECTOR__SINKS__DEBUG__ENABLED = "false" }
 run = [
@@ -51,6 +58,7 @@ run = [
 ]
 
 [tasks."stack:k8s:create"]
+description = "Create a k8s cluster (kind)"
 dir = "stack-k8s"
 run = [
     "ctlptl create registry ctlptl-registry --port=5005",
@@ -71,6 +79,7 @@ run = [
 ]
 
 [tasks."stack:k8s:delete:pre-req"]
+description = "Delete the pre-requirement for cdviz (postgresql, grafana, ...) on a k8s cluster"
 depends = ["stack:k8s:delete:cdviz"]
 dir = "stack-k8s"
 run = ["helmwave down --build  -t pre-req"]
@@ -84,6 +93,7 @@ run = [
 ]
 
 [tasks."stack:k8s:delete:cdviz"]
+description = "Delete cdviz stack (cdviz-collector, cdviz-db) on a k8s cluster"
 dir = "stack-k8s"
 run = ["helmwave down --build  -t cdviz", "kubectl delete namespace cdviz-dev"]
 
@@ -93,19 +103,29 @@ dir = "stack-k8s"
 run = ["helmwave up --build --progress --skip-unchanged -t integration"]
 
 [tasks."stack:k8s:delete:integration"]
+description = "Delete the integrations app (kubewatch,...) on a k8s cluster"
 dir = "stack-k8s"
 run = ["helmwave down --build  -t integration"]
 
 [tasks."stack:k8s:port-forward:grafana"]
+description = "Port-forward the Grafana dashboard to localhost:3000"
 run = ["kubectl port-forward svc/grafana -n grafana 3000:80"]
 
 [tasks."stack:k8s:port-forward:cdviz-db"]
+description = "Port-forward the PostgreSQL database to localhost:5432"
 run = ["kubectl port-forward svc/cdviz-db-rw -n cdviz-dev 5432:5432"]
 
 [tasks."stack:k8s:port-forward:cdviz-collector"]
+description = "Port-forward the cdviz-collector to localhost:8080"
 run = ["kubectl port-forward svc/cdviz-collector -n cdviz-dev 8080:8080"]
 
+[tasks."stack:k8s:deploy"]
+description = "Deploy all the resources (pre-req, cdviz, integrations,...) on a k8s cluster"
+dir = "stack-k8s"
+run = ["helmwave up --build --progress --skip-unchanged"]
+
 [tasks."stack:k8s:delete"]
+description = "Delete a k8s cluster (kind) and its resources"
 dir = "stack-k8s"
 depends = ["stack:k8s:delete:*"]
 run = [
@@ -114,9 +134,10 @@ run = [
 ]
 
 [tasks."stack:k8s:check"]
+description = "check the helwave config to deploy the stack"
 dir = "stack-k8s"
 run = ["helmwave build"]
 
-
 [tasks."ci"]
+description = "Run all the ci tasks"
 depends = ["stack:k8s:check"]

demos/README.md

@@ -0,0 +1,79 @@
+# Demos
+
+This folder contains demos for CDviz.
+
+All commands are run from this folder via `mise` (look at `./.mise.toml` for more details).
+
+```bash
+❯ mise tasks
+Name                                    Description
+ci                                      Run all the ci tasks
+clean                                   Clean / Delete every stacks
+example_01:run                          Launch cdviz-collector cli with content (data & configuration) of the example_01 folder
+stack:compose:delete                    Stop & remove the docker compose demo (and local data)
+stack:compose:down                      Stop the docker compose demo
+stack:compose:up                        Launch the docker compose demo (in foreground)
+stack:db-admin:view                     Open the db-admin UI, adminer (compose demo)
+stack:grafana:view                      Open the Grafana dashboard (compose demo, k8s demo (after port-forward))
+stack:k8s:check                         check the helwave config to deploy the stack
+stack:k8s:create                        Create a k8s cluster (kind)
+stack:k8s:delete                        Delete a k8s cluster (kind) and its resources
+stack:k8s:delete:cdviz                  Delete cdviz stack (cdviz-collector, cdviz-db) on a k8s cluster
+stack:k8s:delete:integration            Delete the integrations app (kubewatch,...) on a k8s cluster
+stack:k8s:delete:pre-req                Delete the pre-requirement for cdviz (postgresql, grafana, ...) on a k8s cluster
+stack:k8s:deploy                        Deploy all the resources (pre-req, cdviz, integrations,...) on a k8s cluster
+stack:k8s:deploy:cdviz                  Deploy cdviz stack (cdviz-collector, cdviz-db) on a k8s cluster
+stack:k8s:deploy:integration            Deploy the integrations app (kubewatch,...) on a k8s cluster
+stack:k8s:deploy:pre-req                Deploy the pre-requirement for cdviz (postgresql, grafana, ...) on a k8s cluster
+stack:k8s:port-forward:cdviz-collector  Port-forward the cdviz-collector to localhost:8080
+stack:k8s:port-forward:cdviz-db         Port-forward the PostgreSQL database to localhost:5432
+stack:k8s:port-forward:grafana          Port-forward the Grafana dashboard to localhost:3000
+```
+
+## Stack Compose
+
+This demo is launched via a Docker Compose demo environment:
+
+- PostgreSQL database + CDviz schema database (migrations)
+- Adminer: to manage the PostgreSQL database
+- Grafana: to visualize the data
+
+Currently, the [`cdviz-collector`] is not launched as part of the docker compose, but it should be launched manually from the host (e.g. via `mise run example_01:run`).
+The [`cdviz-collector`] executable is downloaded from the [release page](https://github.com/cdviz-dev/cdviz-collector/releases) by `mise`.
+
+```bash
+mise run stack:compose:up
+mise run example_01:run
+#...
+mise run stack:grafana:view
+#...
+mise run stack:compose:delete
+```
+
+## Stack K8s
+
+This demo is launched via a local Kubernetes environment, that should reproduce a more realistic setup:
+
+- Pre-requisites for the cdviz full stack
+  - PostgreSQL database (via [CloudNativePG](https://cloudnative-pg.io/))
+  - Grafana
+- CDviz full stack
+  - `cdviz-collector`: to collect the data and send them the `cdviz-db`
+  - `cdviz-db`: to store the data (PostgreSQL)
+  - `cdviz-grafana`: a set of dashboards to visualize the data (Grafana)
+- Integrations (to test the integrations with 3rd party services)
+  - [Kubewatch](https://github.com/robusta-dev/kubewatch): to watch the k8s cluster'events
+
+```bash
+mise run stack:k8s:create
+mise run stack:k8s:deploy:pre-req
+mise run stack:k8s:deploy:cdviz
+mise run stack:k8s:deploy:integration
+#...
+mise run stack:k8s:port-forward:grafana
+mise run stack:grafana:view
+#...
+mise run stack:k8s:delete
+```
+
+  [`cdviz-collector`] <https://github.com/cdviz-dev/cdviz-collector>

demos/stack-k8s/helmwave.yml

@@ -46,7 +46,7 @@ releases:
   - name: cdviz-db
     namespace: cdviz-dev
     # depends_on:
-    #   - cnpg@cnpg
+    #   - name: cnpg@cnpg
     chart: ../../charts/cdviz-db
     # chart:
     #   name: oci://ghcr.io/cdviz-dev/charts/cdviz-db
@@ -66,8 +66,8 @@ releases:
   - name: cdviz-grafana
     namespace: cdviz-dev
     depends_on:
-      # - grafana@grafana
-      - cdviz-db@cdviz-dev
+      # - name: grafana@grafana
+      - name: cdviz-db@cdviz-dev
     chart: ../../charts/cdviz-grafana
     # chart:
     #   name: oci://ghcr.io/cdviz-dev/charts/cdviz-grafana