Skip to content

Add project documentation for the developer-quickstart #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tomncooper merged 3 commits into from
Apr 9, 2026
Merged

Add project documentation for the developer-quickstart #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d28df6e
Add project documentation for the developer-quickstart
tomncooper Apr 2, 2026
5baaed0
Remove mention of minikube tunnel
tomncooper Apr 8, 2026
8341030
Refactor readme to point to docs
tomncooper Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,7 @@
*.iml

### Mac OS ###
**.DS_Store
**.DS_Store

# Hugo local preview site (generated by docs/preview.sh)
.docs-preview/
266 changes: 39 additions & 227 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,17 @@ A Kustomize-based repository for deploying the StreamsHub event-streaming stack

## 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 instance | `apicurio-registry` | In-memory schema registry |
| StreamsHub Console Operator | `streamshub-console` | Manages console instances |
| StreamsHub Console instance | `streamshub-console` | Web UI for Kafka management |
The stack deploys Strimzi Kafka, Apicurio Registry, and StreamsHub Console operators along with their operand instances.
Optional [overlays](docs/overlays/_index.md) add components such as Prometheus metrics.

> **Optional:** The [metrics overlay](#install-with-metrics) adds Prometheus Operator, a Prometheus instance, and Kafka metrics collection via PodMonitors.
See [What Gets Deployed](docs/_index.md#what-gets-deployed) for the full component breakdown.

## Prerequisites

- `kubectl` v1.27 or later (for Kustomize v5.0 `labels` transformer support)
- A running Kubernetes cluster (minikube, KIND, etc.)
- An Ingress controller for StreamsHub Console access (e.g. `minikube addons enable ingress`)
- `kubectl` v1.27 or later
- A running Kubernetes cluster (minikube, KIND, etc.) with an ingress controller

See [Prerequisites](docs/prerequisites.md) for full requirements and cluster setup instructions.

## Quick-Start Install

Expand All @@ -33,232 +28,75 @@ curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/

This script installs operators, waits for them to become ready, then deploys the operands.

### Configuration

The install script accepts the following environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `REPO` | `streamshub/developer-quickstart` | GitHub repository path |
| `REF` | `main` | Git ref, branch, or tag |
| `OVERLAY` | *(empty)* | Overlay to apply (e.g. `metrics`) |
| `TIMEOUT` | `120s` | `kubectl wait` timeout |

Example with a pinned version:

```shell
curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | REF=v1.0.0 bash
```

### Install with Metrics

Deploy the stack with Prometheus metrics collection:
To install with an overlay (e.g. metrics):

```shell
curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/install.sh | OVERLAY=metrics bash
```

This adds the Prometheus Operator and a Prometheus instance (namespace: `monitoring`), enables Kafka metrics via [Strimzi Metrics Reporter](https://strimzi.io/docs/operators/latest/deploying#proc-metrics-kafka-str), and wires Console to display metrics.

## Manual Install

If you prefer to control each step, the stack is installed in two phases:

### Phase 1 — Operators and CRDs

```shell
kubectl apply -k 'https://github.com/streamshub/developer-quickstart//overlays/core/base?ref=main'
```

Wait for the operators to become ready:

```shell
kubectl wait --for=condition=Available deployment/strimzi-cluster-operator -n strimzi --timeout=120s
kubectl wait --for=condition=Available deployment/apicurio-registry-operator -n apicurio-registry --timeout=120s
kubectl wait --for=condition=Available deployment/streamshub-console-operator -n streamshub-console --timeout=120s
```

### Phase 2 — Operands
See [Installation](docs/installation.md) for configuration options, manual install steps, and installing from a local checkout.

```shell
kubectl apply -k 'https://github.com/streamshub/developer-quickstart//overlays/core/stack?ref=main'
```
## Accessing Services

### Manual Install with Metrics

To include the metrics overlay, use the `overlays/metrics` paths instead of `overlays/core`.
After installation, use port-forwarding to access the Console:

```shell
# Phase 1
kubectl create -k 'https://github.com/streamshub/developer-quickstart//overlays/metrics/base?ref=main'
kubectl wait --for=condition=Available deployment/prometheus-operator -n monitoring --timeout=120s
kubectl wait --for=condition=Available deployment/strimzi-cluster-operator -n strimzi --timeout=120s
kubectl wait --for=condition=Available deployment/apicurio-registry-operator -n apicurio-registry --timeout=120s
kubectl wait --for=condition=Available deployment/streamshub-console-operator -n streamshub-console --timeout=120s

# Phase 2
kubectl apply -k 'https://github.com/streamshub/developer-quickstart//overlays/metrics/stack?ref=main'
kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8090:80
```

## Accessing the Console

### Minikube
Open [http://localhost:8090](http://localhost:8090) in your browser.

When using minikube, (if you didn't enable it when you created the minikube cluster) enable the ingress addon and run `minikube tunnel`:

```bash
minikube addons enable ingress
minikube tunnel
```

Then use port-forwarding to access the console:

```bash
kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8080:80
```

Open [http://localhost:8080](http://localhost:8080) in your browser.

### Kind

When using Kind, create the cluster with ingress-ready port mappings:

```bash
cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
kubeadmConfigPatches:
- |
kind: InitConfiguration
nodeRegistration:
kubeletExtraArgs:
node-labels: "ingress-ready=true"
extraPortMappings:
- containerPort: 80
hostPort: 80
protocol: TCP
- containerPort: 443
hostPort: 443
protocol: TCP
EOF
```

Then deploy an ingress controller (e.g. ingress-nginx):

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.12.1/deploy/static/provider/kind/deploy.yaml
kubectl wait --namespace ingress-nginx \
--for=condition=Ready pod \
--selector=app.kubernetes.io/component=controller \
--timeout=120s
```

Use port-forwarding to access the console:

```bash
kubectl port-forward -n streamshub-console svc/streamshub-console-console-service 8080:80
```

Open [http://localhost:8080](http://localhost:8080) in your browser.
See [Accessing Services](docs/accessing-services.md) for Kafka, Apicurio Registry access, and platform-specific instructions.

## Teardown

### Using the Uninstall Script

The uninstall script handles safe teardown with shared-cluster safety checks:
Remove the quick-start stack:

```shell
curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/uninstall.sh | bash

# If installed with the metrics overlay:
curl -sL https://raw.githubusercontent.com/streamshub/developer-quickstart/main/uninstall.sh | OVERLAY=metrics bash
```

The script:
1. Deletes operand custom resources and waits for finalizers to complete
2. Checks each operator group for non-quick-start CRs on the cluster
3. Fully removes operator groups with no shared CRDs
4. For shared operator groups, removes only the operator deployment (retaining CRDs)
5. Reports any retained groups and remaining resources

### Manual Teardown

**Phase 1 — Delete operands:**

```shell
kubectl delete -k 'https://github.com/streamshub/developer-quickstart//overlays/core/stack?ref=main'
```

Wait for all custom resources to be fully removed before proceeding.

**Phase 2 — Delete operators and CRDs:**

> **Warning:** On shared clusters, deleting CRDs will cascade-delete ALL custom resources of that type cluster-wide. Check for non-quick-start resources first:
> ```shell
> kubectl get kafkas -A --selector='!app.kubernetes.io/part-of=streamshub-developer-quickstart'
> ```

```shell
kubectl delete -k 'https://github.com/streamshub/developer-quickstart//overlays/core/base?ref=main'
```
See [Uninstallation](docs/uninstallation.md) for metrics overlay uninstall, manual teardown, and shared-cluster safety details.

For the metrics overlay, use `overlays/metrics/base` and `overlays/metrics/stack` instead.
## Documentation

### Finding Quick-Start Resources
Full documentation is available in the [`docs/`](docs/) directory:

All resources carry the label `app.kubernetes.io/part-of=streamshub-developer-quickstart`:

```shell
kubectl get all -A -l app.kubernetes.io/part-of=streamshub-developer-quickstart
kubectl get crds,clusterroles,clusterrolebindings -l app.kubernetes.io/part-of=streamshub-developer-quickstart
```
- [Prerequisites](docs/prerequisites.md) — requirements and cluster setup
- [Installation](docs/installation.md) — all install methods, configuration, and local development
- [Accessing Services](docs/accessing-services.md) — Console, Kafka, and Registry access
- [Architecture](docs/architecture.md) — deployment model, Kustomize structure, versioning
- [Overlays](docs/overlays/_index.md) — optional extensions (metrics, etc.)
- [Uninstallation](docs/uninstallation.md) — safe teardown on any cluster
- [Troubleshooting](docs/troubleshooting.md) — common issues and diagnostics

## Development

### Updating Component Versions

Use the `update-version.sh` script to update component versions:
For development workflows including updating component versions and testing scripts locally, see:
- [Updating Component Versions](docs/architecture.md#updating-component-versions)
- [Install from a Local Checkout](docs/installation.md#install-from-a-local-checkout)

```shell
# List available versions
./update-version.sh --list strimzi

# Preview changes
./update-version.sh --dry-run strimzi 0.52.0
### Previewing Documentation Locally

# Check if a release exists
./update-version.sh --check apicurio-registry 3.2.0
The `docs/` directory contains the project documentation. To preview it locally with Hugo:

# Update a component
./update-version.sh strimzi 0.52.0
```shell
./docs/preview.sh
```

Supported components: `strimzi`, `apicurio-registry`, `streamshub-console`, `prometheus-operator`

### Testing scripts locally
This starts a local server at [http://localhost:1313/docs/](http://localhost:1313/docs/) with live-reload.
Press `Ctrl+C` to stop.

When developing changes to the kustomization files, use the `LOCAL_DIR` environment
variable to point the install and uninstall scripts at your local checkout instead
of the remote GitHub repository:
To generate static HTML instead:

```shell
# Install from local repo
LOCAL_DIR=. ./install.sh

# Uninstall from local repo
LOCAL_DIR=. ./uninstall.sh
./docs/preview.sh build
```

When `LOCAL_DIR` is set, `REPO` and `REF` are ignored — the scripts resolve
kustomization paths relative to the given directory.

You can also provide an absolute path:
The output is written to `.docs-preview/public/`.

```shell
LOCAL_DIR=/home/user/repos/developer-quickstart ./install.sh
```
**Requirements:** `hugo`, `git`, and `go` must be installed.
The script handles theme fetching and site configuration automatically.

## Testing

Expand Down Expand Up @@ -327,29 +165,3 @@ The scripts accept configuration via environment variables:
| `CONDITION_OVERRIDES` | VerifyInstall | *(empty)* | Space-separated `apiGroup=Condition` pairs |
| `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
```
47 changes: 47 additions & 0 deletions docs/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading
Loading