Skip to content

Commit 353dc87

Browse files
tomncoopertomncooper
committed
Add project documentation for the developer-quickstart
Introduce Hugo-compatible docs covering installation, prerequisites, architecture, accessing services, overlays, metrics, troubleshooting and uninstallation. * Add docs folder for content pages and overlays subsection * Add docs/preview.sh script for local Hugo preview and static builds * Add local preview instructions to README.md * Move repository structure section from README into docs * Update .gitignore to exclude .docs-preview/ directory Signed-off-by: Thomas Cooper <code@tomcooper.dev>
1 parent 6c7f498 commit 353dc87

12 files changed

Lines changed: 936 additions & 26 deletions

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,7 @@
66
*.iml
77

88
### Mac OS ###
9-
**.DS_Store
9+
**.DS_Store
10+
11+
# Hugo local preview site (generated by docs/preview.sh)
12+
.docs-preview/

‎README.md‎

Lines changed: 22 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,28 @@ You can also provide an absolute path:
260260
LOCAL_DIR=/home/user/repos/developer-quickstart ./install.sh
261261
```
262262

263+
### Previewing Documentation Locally
264+
265+
The `docs/` directory contains the project documentation. To preview it locally with Hugo:
266+
267+
```shell
268+
./docs/preview.sh
269+
```
270+
271+
This starts a local server at [http://localhost:1313/docs/](http://localhost:1313/docs/) with live-reload.
272+
Press `Ctrl+C` to stop.
273+
274+
To generate static HTML instead:
275+
276+
```shell
277+
./docs/preview.sh build
278+
```
279+
280+
The output is written to `.docs-preview/public/`.
281+
282+
**Requirements:** `hugo`, `git`, and `go` must be installed.
283+
The script handles theme fetching and site configuration automatically.
284+
263285
## Testing
264286

265287
### CI Smoke Tests
@@ -328,28 +350,3 @@ The scripts accept configuration via environment variables:
328350
| `PLATFORMS` | ComputeTestMatrix | `minikube kind` | Space-separated list of target platforms |
329351
| `LOG_TAIL_LINES` | Debug | `30` | Number of log lines to tail per pod |
330352

331-
## Repository Structure
332-
333-
```
334-
components/ # Reusable Kustomize components
335-
├── core/ # Core stack component
336-
│ ├── base/ # Operators & CRDs
337-
│ │ ├── strimzi-operator/ # Strimzi Kafka Operator
338-
│ │ ├── apicurio-registry-operator/ # Apicurio Registry Operator
339-
│ │ └── streamshub-console-operator/ # StreamsHub Console Operator
340-
│ └── stack/ # Operands (Custom Resources)
341-
│ ├── kafka/ # Single-node Kafka cluster
342-
│ ├── apicurio-registry/ # In-memory registry instance
343-
│ └── streamshub-console/ # Console instance
344-
└── metrics/ # Prometheus metrics component
345-
├── base/ # Prometheus Operator
346-
└── stack/ # Prometheus instance, PodMonitors, patches
347-
348-
overlays/ # Deployable configurations
349-
├── core/ # Default install (core only)
350-
│ ├── base/ # Phase 1: Operators & CRDs
351-
│ └── stack/ # Phase 2: Operands
352-
└── metrics/ # Core + Prometheus metrics
353-
├── base/ # Phase 1: Operators & CRDs + Prometheus Operator
354-
└── stack/ # Phase 2: Operands + Prometheus instance & monitors
355-
```

‎docs/_index.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
+++
2+
title = 'Developer Quick-Start'
3+
linkTitle = 'Developer Quick-Start'
4+
weight = 0
5+
[[cascade]]
6+
type = 'docs'
7+
+++
8+
9+
# Developer Quick-Start
10+
11+
Please make sure you have all the [prerequisites](prerequisites.md) covered first.
12+
Then you can deploy a complete, open-source, event-streaming stack on your local Kubernetes cluster (e.g. MiniKube, KIND) with a single command:
13+
14+
```shell
15+
curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | bash
16+
```
17+
18+
The script installs operators, waits for readiness, then deploys all services.
19+
The full stack is typically ready in under five minutes.
20+
21+
> **Note:** This is a **development-only** configuration. Resource limits, security settings, and storage are not suitable for production use.
22+
23+
## What Gets Deployed
24+
25+
| Component | Namespace | Description |
26+
|-------------------------------|----------------------|-----------------------------------|
27+
| Strimzi Kafka Operator | `strimzi` | Manages Kafka clusters via CRDs |
28+
| Kafka cluster (`dev-cluster`) | `kafka` | Single-node Kafka for development |
29+
| Apicurio Registry Operator | `apicurio-registry` | Manages schema registry instances |
30+
| Apicurio Registry | `apicurio-registry` | In-memory schema registry |
31+
| StreamsHub Console Operator | `streamshub-console` | Manages console instances |
32+
| StreamsHub Console | `streamshub-console` | Web UI for Kafka management |
33+
34+
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:
35+
36+
```shell
37+
curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | OVERLAY=<name> bash
38+
```
39+
40+
## Next Steps
41+
42+
- [Prerequisites](prerequisites.md) — what you need before installing.
43+
- [Installation](installation.md) — all installation methods and options.
44+
- [Accessing Services](accessing-services.md) — open the Console, connect to Kafka.
45+
- [Overlays](overlays/) - look at the what additional components and features can be added with the provided overlays.
46+
- [Uninstallation](uninstallation.md) — safe teardown on any cluster.
47+
- [Troubleshooting](troubleshooting.md) - help with common issues.

‎docs/accessing-services.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
+++
2+
title = 'Accessing Services'
3+
weight = 3
4+
+++
5+
6+
# Accessing Services
7+
8+
## StreamsHub Console
9+
10+
### Ingress Access
11+
12+
For the Console to startup correctly and be accessible, you need an Ingress controller running in your cluster.
13+
14+
#### minikube
15+
16+
Enable the ingress addon (if not already enabled) and start a tunnel:
17+
18+
```shell
19+
minikube addons enable ingress
20+
minikube tunnel
21+
```
22+
23+
You will need to leave the tunnel running in an open terminal.
24+
Switch to a new terminal and use port-forwarding to access the console:
25+
26+
```bash
27+
kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8090:80
28+
```
29+
30+
Open [http://localhost:8090](http://localhost:8090) in your browser.
31+
32+
#### KIND
33+
34+
If you created your KIND cluster with the port mappings described in [Prerequisites](prerequisites.md), and deployed ingress-nginx:
35+
Use port-forwarding to access the console:
36+
37+
```bash
38+
kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8090:80
39+
```
40+
41+
Open [http://localhost:8090](http://localhost:8090) in your browser.
42+
43+
44+
## Kafka
45+
46+
The Kafka cluster is accessible within the Kubernetes cluster at:
47+
48+
```
49+
dev-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092
50+
```
51+
52+
### Port-Forwarding
53+
54+
To access Kafka from outside the cluster:
55+
56+
```shell
57+
kubectl port-forward -n kafka svc/dev-cluster-kafka-bootstrap 9092:9092
58+
```
59+
60+
Then connect your client to `localhost:9092`.
61+
62+
### Producing and Consuming Messages
63+
64+
From within the cluster, you can use the Kafka CLI tools:
65+
66+
```shell
67+
# Start a producer
68+
kubectl run kafka-producer -it --rm --image=quay.io/strimzi/kafka:0.51.0-kafka-4.2.0 \
69+
--restart=Never -- bin/kafka-console-producer.sh \
70+
--bootstrap-server dev-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092 \
71+
--topic test
72+
73+
# Start a consumer (in a separate terminal)
74+
kubectl run kafka-consumer -it --rm --image=quay.io/strimzi/kafka:0.51.0-kafka-4.2.0 \
75+
--restart=Never -- bin/kafka-console-consumer.sh \
76+
--bootstrap-server dev-cluster-kafka-bootstrap.kafka.svc.cluster.local:9092 \
77+
--topic test --from-beginning
78+
```
79+
80+
## Apicurio Registry
81+
82+
The registry has two services accessible within the cluster:
83+
84+
- API: `apicurio-registry-app-service.apicurio-registry.svc.cluster.local:8080`
85+
- UI: `apicurio-registry-ui-service.apicurio-registry.svc.cluster.local:8080`
86+
87+
### Port-Forwarding
88+
89+
The UI is a browser application that connects to the API backend at `localhost:8080` by default.
90+
To use the UI, you must port-forward **both** the API and UI services.
91+
92+
#### API
93+
94+
The API service must be forwarded to port 8080 for the UI to function:
95+
96+
```shell
97+
kubectl port-forward -n apicurio-registry svc/apicurio-registry-app-service 8080:8080
98+
```
99+
100+
You can query the API directly:
101+
102+
```shell
103+
curl http://localhost:8080/apis/registry/v3/search/artifacts
104+
```
105+
106+
#### UI
107+
108+
In a separate terminal, forward the UI service:
109+
110+
```shell
111+
kubectl port-forward -n apicurio-registry svc/apicurio-registry-ui-service 8081:8080
112+
```
113+
114+
Open [http://localhost:8081](http://localhost:8081) in your browser.
115+
116+
## Overlay Services
117+
118+
If you installed with an overlay, it may deploy additional services.
119+
See the specific overlay page under [Overlays](overlays/_index.md) for access instructions.

‎docs/architecture.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
+++
2+
title = 'Architecture'
3+
weight = 6
4+
+++
5+
6+
# Architecture
7+
8+
## Two-Phase Deployment
9+
10+
The event stack is deployed in two sequential phases:
11+
12+
**Phase 1 - The Base - Operators and CRDs:** Deploys operator Deployments, RBAC resources, and Custom Resource Definitions.
13+
The install script waits for each operator to become ready before proceeding.
14+
15+
**Phase 2 - The Stack - Operands:** Deploys the actual workloads as Custom Resources (Kafka, ApicurioRegistry3, Console).
16+
Operators must be running to process these resources.
17+
18+
This separation exists for three reasons:
19+
20+
1. **CRD registration** — Kubernetes must register CRDs before it can accept custom resources of that type
21+
2. **Operator readiness** — operators must be running to reconcile their custom resources
22+
3. **Safe teardown** — during uninstall, operands are deleted first while operators are still alive to process finalizers
23+
24+
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.
25+
26+
## Kustomize Structure
27+
28+
The repository uses a component-based Kustomize architecture:
29+
30+
```
31+
components/ # Reusable Kustomize components
32+
├── core/
33+
│ ├── base/ # Component: operators & CRDs
34+
│ └── stack/ # Component: operands
35+
└── metrics/ # Optional metrics component
36+
├── base/
37+
└── stack/
38+
overlays/ # Deployable configurations
39+
├── core/ # Default (no metrics)
40+
│ ├── base/ # Phase 1: components/core/base
41+
│ └── stack/ # Phase 2: components/core/stack
42+
└── metrics/ # Core + Prometheus
43+
├── base/ # Phase 1: core/base + metrics/base
44+
└── stack/ # Phase 2: core/stack + metrics/stack
45+
```
46+
47+
**Components** are reusable building blocks (Kustomize `Component` kind).
48+
They define operators, operands, and patches but are not directly deployable.
49+
50+
**Overlays** compose components into deployable configurations.
51+
Each overlay has a `base` (Phase 1) and `stack` (Phase 2) directory.
52+
The `metrics` overlay includes everything from `core` plus the Prometheus components.
53+
54+
## Resource Labeling
55+
56+
Every resource deployed by the quick-start carries the label:
57+
58+
```yaml
59+
app.kubernetes.io/part-of: streamshub-developer-quickstart
60+
```
61+
62+
This label is applied by the Kustomize `labels` transformer and serves two purposes:
63+
64+
- Resource discovery — find all quick-start resources with a single label selector
65+
- 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
66+
67+
## Namespace Isolation
68+
69+
Each component runs in its own namespace:
70+
71+
| Namespace | Contents |
72+
|----------------------|----------------------------------------------------|
73+
| `strimzi` | Strimzi Kafka Operator |
74+
| `kafka` | Kafka cluster (`dev-cluster`) |
75+
| `apicurio-registry` | Registry Operator and instance |
76+
| `streamshub-console` | Console Operator and instance |
77+
| `monitoring` | Prometheus Operator and instance (metrics overlay) |
78+
79+
## Updating Component Versions
80+
81+
Use the `update-version.sh` script to manage operator versions:
82+
83+
```shell
84+
# List available versions for a component
85+
./update-version.sh --list strimzi
86+
87+
# Preview changes without modifying files
88+
./update-version.sh --dry-run strimzi 0.52.0
89+
90+
# Check if a specific release exists
91+
./update-version.sh --check apicurio-registry 3.2.0
92+
93+
# Apply the update
94+
./update-version.sh strimzi 0.52.0
95+
```
96+
97+
Supported components: `strimzi`, `apicurio-registry`, `streamshub-console`, `prometheus-operator`
98+
99+
The script updates the remote resource URLs in the relevant `kustomization.yaml` files to point to the new version's release artifacts.

0 commit comments

Comments
 (0)