streamshub · tomncooper · Apr 2, 2026
diff --git a/.gitignore b/.gitignore
@@ -6,4 +6,7 @@
 *.iml
 
 ### Mac OS ###
-**.DS_Store
+**.DS_Store
+
+# Hugo local preview site (generated by docs/preview.sh)
+.docs-preview/
diff --git a/README.md b/README.md
@@ -260,6 +260,28 @@ You can also provide an absolute path:
 LOCAL_DIR=/home/user/repos/developer-quickstart ./install.sh
 ```
 
+### Previewing Documentation Locally
+
+The `docs/` directory contains the project documentation. To preview it locally with Hugo:
+
+```shell
+./docs/preview.sh
+```
+
+This starts a local server at [http://localhost:1313/docs/](http://localhost:1313/docs/) with live-reload. 
+Press `Ctrl+C` to stop.
+
+To generate static HTML instead:
+
+```shell
+./docs/preview.sh build
+```
+
+The output is written to `.docs-preview/public/`.
+
+**Requirements:** `hugo`, `git`, and `go` must be installed. 
+The script handles theme fetching and site configuration automatically.
+
 ## Testing
 
 ### CI Smoke Tests
@@ -328,28 +350,3 @@ The scripts accept configuration via environment variables:
 | `PLATFORMS` | ComputeTestMatrix | `minikube kind` | Space-separated list of target platforms |
 | `LOG_TAIL_LINES` | Debug | `30` | Number of log lines to tail per pod |
 
-## Repository Structure
-
-```
-components/                         # Reusable Kustomize components
-├── core/                           # Core stack component
-│   ├── base/                       # Operators & CRDs
-│   │   ├── strimzi-operator/       # Strimzi Kafka Operator
-│   │   ├── apicurio-registry-operator/  # Apicurio Registry Operator
-│   │   └── streamshub-console-operator/ # StreamsHub Console Operator
-│   └── stack/                      # Operands (Custom Resources)
-│       ├── kafka/                  # Single-node Kafka cluster
-│       ├── apicurio-registry/      # In-memory registry instance
-│       └── streamshub-console/     # Console instance
-└── metrics/                        # Prometheus metrics component
-    ├── base/                       # Prometheus Operator
-    └── stack/                      # Prometheus instance, PodMonitors, patches
-
-overlays/                           # Deployable configurations
-├── core/                           # Default install (core only)
-│   ├── base/                       # Phase 1: Operators & CRDs
-│   └── stack/                      # Phase 2: Operands
-└── metrics/                        # Core + Prometheus metrics
-    ├── base/                       # Phase 1: Operators & CRDs + Prometheus Operator
-    └── stack/                      # Phase 2: Operands + Prometheus instance & monitors
-```
diff --git a/docs/_index.md b/docs/_index.md
@@ -0,0 +1,47 @@
++++
+title = 'Developer Quick-Start'
+linkTitle = 'Developer Quick-Start'
+weight = 0
+[[cascade]]
+    type = 'docs'
++++
+
+# Developer Quick-Start
+
+Please make sure you have all the [prerequisites](prerequisites.md) covered first.
+Then you can deploy a complete, open-source, event-streaming stack on your local Kubernetes cluster (e.g. MiniKube, KIND) with a single command:
+
+```shell
+curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | bash
+```
+
+The script installs operators, waits for readiness, then deploys all services. 
+The full stack is typically ready in under five minutes.
+
+> **Note:** This is a **development-only** configuration. Resource limits, security settings, and storage are not suitable for production use.
+
+## What Gets Deployed
+
+| Component                     | Namespace            | Description                       |
+|-------------------------------|----------------------|-----------------------------------|
+| Strimzi Kafka Operator        | `strimzi`            | Manages Kafka clusters via CRDs   |
+| Kafka cluster (`dev-cluster`) | `kafka`              | Single-node Kafka for development |
+| Apicurio Registry Operator    | `apicurio-registry`  | Manages schema registry instances |
+| Apicurio Registry             | `apicurio-registry`  | In-memory schema registry         |
+| StreamsHub Console Operator   | `streamshub-console` | Manages console instances         |
+| StreamsHub Console            | `streamshub-console` | Web UI for Kafka management       |
+
+Optional [overlays](overlays/_index.md) can extend the core stack with additional components such as Prometheus metrics. Install with an overlay by setting the `OVERLAY` variable:
+
+```shell
+curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | OVERLAY=<name> bash
+```
+
+## Next Steps
+
+- [Prerequisites](prerequisites.md) — what you need before installing.
+- [Installation](installation.md) — all installation methods and options.
+- [Accessing Services](accessing-services.md) — open the Console, connect to Kafka.
+- [Overlays](overlays/) - look at the what additional components and features can be added with the provided overlays.
+- [Uninstallation](uninstallation.md) — safe teardown on any cluster.
+- [Troubleshooting](troubleshooting.md) - help with common issues.
diff --git a/docs/accessing-services.md b/docs/accessing-services.md
@@ -0,0 +1,119 @@
++++
+title = 'Accessing Services'
+weight = 3
++++
+
+# Accessing Services
+
+## StreamsHub Console
+
+### Ingress Access
+
+For the Console to startup correctly and be accessible, you need an Ingress controller running in your cluster.
+
+#### minikube
+
+Enable the ingress addon (if not already enabled) and start a tunnel:
+
+```shell
+minikube addons enable ingress
+minikube tunnel
+```
+
+You will need to leave the tunnel running in an open terminal.
+Switch to a new terminal and use port-forwarding to access the console:
+
+```bash
+kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8090:80
+```
+
+Open [http://localhost:8090](http://localhost:8090) in your browser.
+
+#### KIND
+
+If you created your KIND cluster with the port mappings described in [Prerequisites](prerequisites.md), and deployed ingress-nginx:
+Use port-forwarding to access the console:
+
+```bash
+kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8090:80
+```
+
+Open [http://localhost:8090](http://localhost:8090) in your browser.
+
+
+## Kafka
+
+The Kafka cluster is accessible within the Kubernetes cluster at:
+
+```
+dev-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092
+```
+
+### Port-Forwarding
+
+To access Kafka from outside the cluster:
+
+```shell
+kubectl port-forward -n kafka svc/dev-cluster-kafka-bootstrap 9092:9092
+```
+
+Then connect your client to `localhost:9092`.
+
+### Producing and Consuming Messages
+
+From within the cluster, you can use the Kafka CLI tools:
+
+```shell
+# Start a producer
+kubectl run kafka-producer -it --rm --image=quay.io/strimzi/kafka:0.51.0-kafka-4.2.0 \
+  --restart=Never -- bin/kafka-console-producer.sh \
+  --bootstrap-server dev-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092 \
+  --topic test
+
+# Start a consumer (in a separate terminal)
+kubectl run kafka-consumer -it --rm --image=quay.io/strimzi/kafka:0.51.0-kafka-4.2.0 \
+  --restart=Never -- bin/kafka-console-consumer.sh \
+  --bootstrap-server dev-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092 \
+  --topic test --from-beginning
+```
+
+## Apicurio Registry
+
+The registry has two services accessible within the cluster:
+
+- API: `apicurio-registry-app-service.apicurio-registry.svc.cluster.local:8080`
+- UI: `apicurio-registry-ui-service.apicurio-registry.svc.cluster.local:8080`
+
+### Port-Forwarding
+
+The UI is a browser application that connects to the API backend at `localhost:8080` by default.
+To use the UI, you must port-forward **both** the API and UI services.
+
+#### API
+
+The API service must be forwarded to port 8080 for the UI to function:
+
+```shell
+kubectl port-forward -n apicurio-registry svc/apicurio-registry-app-service 8080:8080
+```
+
+You can query the API directly:
+
+```shell
+curl http://localhost:8080/apis/registry/v3/search/artifacts
+```
+
+#### UI
+
+In a separate terminal, forward the UI service:
+
+```shell
+kubectl port-forward -n apicurio-registry svc/apicurio-registry-ui-service 8081:8080
+```
+
+Open [http://localhost:8081](http://localhost:8081) in your browser.
+
+## Overlay Services
+
+If you installed with an overlay, it may deploy additional services. 
+See the specific overlay page under [Overlays](overlays/_index.md) for access instructions.
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -0,0 +1,99 @@
++++
+title = 'Architecture'
+weight = 6
++++
+
+# Architecture
+
+## Two-Phase Deployment
+
+The event stack is deployed in two sequential phases:
+
+**Phase 1 - The Base - Operators and CRDs:** Deploys operator Deployments, RBAC resources, and Custom Resource Definitions. 
+The install script waits for each operator to become ready before proceeding.
+
+**Phase 2 - The Stack - Operands:** Deploys the actual workloads as Custom Resources (Kafka, ApicurioRegistry3, Console). 
+Operators must be running to process these resources.
+
+This separation exists for three reasons:
+
+1. **CRD registration** — Kubernetes must register CRDs before it can accept custom resources of that type
+2. **Operator readiness** — operators must be running to reconcile their custom resources
+3. **Safe teardown** — during uninstall, operands are deleted first while operators are still alive to process finalizers
+
+The install script uses `kubectl apply --server-side` for Phase 1 to handle large CRDs (such as those from the Prometheus Operator) that exceed the annotation size limit used by client-side apply.
+
+## Kustomize Structure
+
+The repository uses a component-based Kustomize architecture:
+
+```
+components/                           # Reusable Kustomize components
+├── core/
+│   ├── base/                         # Component: operators & CRDs
+│   └── stack/                        # Component: operands
+└── metrics/                          # Optional metrics component
+    ├── base/
+    └── stack/
+overlays/                             # Deployable configurations
+├── core/                             # Default (no metrics)
+│   ├── base/                         # Phase 1: components/core/base
+│   └── stack/                        # Phase 2: components/core/stack
+└── metrics/                          # Core + Prometheus
+    ├── base/                         # Phase 1: core/base + metrics/base
+    └── stack/                        # Phase 2: core/stack + metrics/stack
+```
+
+**Components** are reusable building blocks (Kustomize `Component` kind). 
+They define operators, operands, and patches but are not directly deployable.
+
+**Overlays** compose components into deployable configurations. 
+Each overlay has a `base` (Phase 1) and `stack` (Phase 2) directory. 
+The `metrics` overlay includes everything from `core` plus the Prometheus components.
+
+## Resource Labeling
+
+Every resource deployed by the quick-start carries the label:
+
+```yaml
+app.kubernetes.io/part-of: streamshub-developer-quickstart
+```
+
+This label is applied by the Kustomize `labels` transformer and serves two purposes:
+
+- Resource discovery — find all quick-start resources with a single label selector
+- Shared-cluster safety — the uninstall script uses label selectors to distinguish quick-start resources from user-created ones, preventing accidental deletion of CRDs that other deployments depend on
+
+## Namespace Isolation
+
+Each component runs in its own namespace:
+
+| Namespace            | Contents                                           |
+|----------------------|----------------------------------------------------|
+| `strimzi`            | Strimzi Kafka Operator                             |
+| `kafka`              | Kafka cluster (`dev-cluster`)                      |
+| `apicurio-registry`  | Registry Operator and instance                     |
+| `streamshub-console` | Console Operator and instance                      |
+| `monitoring`         | Prometheus Operator and instance (metrics overlay) |
+
+## Updating Component Versions
+
+Use the `update-version.sh` script to manage operator versions:
+
+```shell
+# List available versions for a component
+./update-version.sh --list strimzi
+
+# Preview changes without modifying files
+./update-version.sh --dry-run strimzi 0.52.0
+
+# Check if a specific release exists
+./update-version.sh --check apicurio-registry 3.2.0
+
+# Apply the update
+./update-version.sh strimzi 0.52.0
+```
+
+Supported components: `strimzi`, `apicurio-registry`, `streamshub-console`, `prometheus-operator`
+
+The script updates the remote resource URLs in the relevant `kustomization.yaml` files to point to the new version's release artifacts.