Adds the practical elements for lesson 1 of the GitOps tutorial series.

README.md

@@ -10,6 +10,10 @@ Documentation, including overviews and tutorials can be found in the `docs` fold
 - See the main StreamsHub site's [README](https://github.com/streamshub/streamshub-site?tab=readme-ov-file#pulling-dependant-sources) for more details on the docs generation process.
 - See the Flink SQL Examples [docs](https://github.com/streamshub/flink-sql-examples/tree/main/docs) for an example of how documentation can be laid out.
 
+## Tutorials
+
+Hands-on GitOps tutorials can be found under the [lessons](./lessons) folder. Start with [lessons/00-setup](./lessons/00-setup) to spin up the shared local environment, then follow each numbered lesson.
+
 ## Example Code
 
-Example code can be found under the [examples](./examples) folder.
+Production-oriented example code can be found under the [examples](./examples) folder.

lessons/00-setup/README.md

@@ -0,0 +1,74 @@
+# Getting Started
+
+This directory sets up the shared infrastructure for the GitOps tutorial series. Run `setup.sh` once before starting any lesson.
+
+---
+
+## Prerequisites
+
+| Tool | Purpose | Install |
+|------|---------|---------|
+| **Docker** or **Podman** | Container runtime | [docker](https://docs.docker.com/get-docker/)<br>[podman](https://podman.io/docs/installation) |
+| **KinD** (v0.20+) | Local Kubernetes clusters | [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) |
+| **kubectl** | Kubernetes CLI | [kubectl](https://kubernetes.io/docs/tasks/tools/) |
+| **git** | Version control | [git-scm.com](https://git-scm.com/) |
+| **curl** | HTTP requests | Usually pre-installed |
+
+**System requirements:** ~8 GB of available memory for Docker/Podman.
+
+---
+
+## Setup
+
+Run the setup script from this directory:
+
+```bash
+./setup.sh
+```
+
+This takes approximately 8 minutes and creates a fully self-contained local environment:
+
+1. A **KinD** Kubernetes cluster (`gitops-tutorial`) running on your machine
+2. **ArgoCD** — the GitOps engine that watches Git and applies changes
+3. **Strimzi** — the operator that manages Kafka resources on Kubernetes
+4. **Gitea** — a lightweight Git server running inside the cluster, reachable at `http://localhost:3001`
+5. A Git repository in Gitea containing the base Kafka configuration
+6. An ArgoCD `Application` configured to watch that repository
+7. A running Kafka cluster, already deployed via the GitOps workflow
+
+When the script finishes, it prints the ArgoCD admin password and tells you which lesson prep script to run next.
+
+---
+
+## Starting a lesson
+
+After setup completes, follow the lesson guide of your choice:
+* [Lesson 1: Your First GitOps Change](../01-lesson-1/README.md)
+
+---
+
+## Teardown
+
+When you are done with all lessons, delete the cluster to remove everything:
+
+```bash
+./teardown.sh
+```
+
+---
+
+## Troubleshooting
+
+**Docker is not running**
+Start Docker Desktop or your container runtime and run `./setup.sh` again.
+
+**Port 3001 is already in use**
+Another application is using port 3001. Stop that application, or change the port in `kind-config.yaml` (update both `hostPort` and the `nodePort` in `gitea/deployment.yaml` to match).
+
+**Kafka cluster is not becoming ready**
+Kafka takes a few minutes to start, especially on machines with limited resources. Check pod status:
+
+```bash
+kubectl get pods -n kafka-tutorial
+kubectl describe kafka my-cluster -n kafka-tutorial
+```

lessons/00-setup/argocd/application.yaml

@@ -0,0 +1,23 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: kafka-tutorial
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: http://gitea-http.gitea.svc:3000/tutorial-user/streamshub-gitops.git
+    targetRevision: main
+    path: manifests
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: kafka-tutorial
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    managedNamespaceMetadata:
+      labels:
+        argocd.argoproj.io/managed-by: argocd
+    syncOptions:
+      - CreateNamespace=true

lessons/00-setup/argocd/repository-secret.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: gitea-repo
+  namespace: argocd
+  labels:
+    argocd.argoproj.io/secret-type: repository
+type: Opaque
+stringData:
+  type: git
+  url: http://gitea-http.gitea.svc:3000/tutorial-user/streamshub-gitops.git
+  username: tutorial-user
+  password: tutorial-password
+  insecure: "true"

lessons/00-setup/base-manifests/combined-pool.yaml

@@ -0,0 +1,26 @@
+apiVersion: kafka.strimzi.io/v1
+kind: KafkaNodePool
+metadata:
+  name: combined
+  namespace: kafka-tutorial
+  labels:
+    strimzi.io/cluster: my-cluster
+spec:
+  replicas: 1
+  roles:
+    - controller
+    - broker
+  storage:
+    type: jbod
+    volumes:
+      - id: 0
+        type: persistent-claim
+        size: 2Gi
+        deleteClaim: true
+  resources:
+    requests:
+      memory: 512Mi
+      cpu: 250m
+    limits:
+      memory: 1Gi
+      cpu: 500m

lessons/00-setup/base-manifests/kafka.yaml

@@ -0,0 +1,29 @@
+apiVersion: kafka.strimzi.io/v1
+kind: Kafka
+metadata:
+  name: my-cluster
+  namespace: kafka-tutorial
+spec:
+  kafka:
+    version: 4.2.0
+    metadataVersion: "4.2-IV0"
+    listeners:
+      - name: plain
+        port: 9092
+        type: internal
+        tls: false
+    config:
+      offsets.topic.replication.factor: 1
+      transaction.state.log.replication.factor: 1
+      transaction.state.log.min.isr: 1
+      default.replication.factor: 1
+      min.insync.replicas: 1
+  entityOperator:
+    topicOperator:
+      resources:
+        requests:
+          cpu: 100m
+          memory: 256Mi
+        limits:
+          cpu: 250m
+          memory: 384Mi

lessons/00-setup/base-manifests/kustomization.yaml

@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - combined-pool.yaml
+  - kafka.yaml

lessons/00-setup/base-manifests/namespace.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: kafka-tutorial
+  labels:
+    name: kafka-tutorial

lessons/00-setup/gitea/deployment.yaml

@@ -0,0 +1,74 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: gitea
+  namespace: gitea
+  labels:
+    app: gitea
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: gitea
+  template:
+    metadata:
+      labels:
+        app: gitea
+    spec:
+      containers:
+        - name: gitea
+          image: gitea/gitea:1.23-rootless
+          ports:
+            - containerPort: 3000
+              name: http
+          env:
+            - name: GITEA__database__DB_TYPE
+              value: sqlite3
+            - name: GITEA__security__INSTALL_LOCK
+              value: "true"
+            - name: GITEA__server__ROOT_URL
+              value: http://localhost:3001
+            - name: GITEA__server__HTTP_PORT
+              value: "3000"
+            - name: GITEA__service__DISABLE_REGISTRATION
+              value: "true"
+          volumeMounts:
+            - name: data
+              mountPath: /var/lib/gitea
+            - name: config
+              mountPath: /etc/gitea
+          resources:
+            requests:
+              cpu: 100m
+              memory: 256Mi
+            limits:
+              cpu: 500m
+              memory: 512Mi
+          readinessProbe:
+            httpGet:
+              path: /api/v1/version
+              port: 3000
+            initialDelaySeconds: 10
+            periodSeconds: 5
+      volumes:
+        - name: data
+          emptyDir: {}
+        - name: config
+          emptyDir: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: gitea-http
+  namespace: gitea
+  labels:
+    app: gitea
+spec:
+  type: NodePort
+  selector:
+    app: gitea
+  ports:
+    - port: 3000
+      targetPort: 3000
+      nodePort: 30003
+      name: http

lessons/00-setup/gitea/kustomization.yaml

@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - deployment.yaml

lessons/00-setup/gitea/namespace.yaml

@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: gitea
+  labels:
+    name: gitea

lessons/00-setup/kind-config.yaml

@@ -0,0 +1,8 @@
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+  - role: control-plane
+    extraPortMappings:
+      - containerPort: 30003
+        hostPort: 3001
+        protocol: TCP