Add examples, concepts, and getting started documentation

config/rbac/kustomization.yaml

@@ -29,13 +29,13 @@ resources:
 # default, aiding admins in cluster management. Those roles are
 # not used by the koptan itself. You can comment the following lines
 # if you do not want those helpers be installed with your Project.
-- javaapp_admin_role.yaml
-- javaapp_editor_role.yaml
-- javaapp_viewer_role.yaml
-- dotnetapp_admin_role.yaml
-- dotnetapp_editor_role.yaml
-- dotnetapp_viewer_role.yaml
-- goapp_admin_role.yaml
-- goapp_editor_role.yaml
-- goapp_viewer_role.yaml
+  - javaapp_admin_role.yaml
+  - javaapp_editor_role.yaml
+  - javaapp_viewer_role.yaml
+  - dotnetapp_admin_role.yaml
+  - dotnetapp_editor_role.yaml
+  - dotnetapp_viewer_role.yaml
+  - goapp_admin_role.yaml
+  - goapp_editor_role.yaml
+  - goapp_viewer_role.yaml
 

docs/concepts/apps.md

@@ -0,0 +1,36 @@
+# Apps
+
+Koptan provides application resources that represent application definitions at a higher level than native Kubernetes resources.
+
+## Supported App Resources
+
+Koptan currently defines:
+
+- `GoApp`
+- `DotnetApp`
+- `JavaApp`
+
+These types are defined in:
+
+- `api/v1alpha/goapp_types.go`
+- `api/v1alpha/dotnetapp_types.go`
+- `api/v1alpha/javaapp_types.go`
+
+## Purpose
+
+An App resource is intended to describe an application in a language-aware way.
+
+Instead of directly creating lower-level Kubernetes objects, users define an application using an App custom resource and let Koptan reconcile the desired state.
+
+## Why Separate App Types?
+
+Different languages often require different build or packaging behavior.
+
+For that reason, Koptan models them as separate resources rather than a single generic application type.
+
+## Related Resources
+
+An App resource is related to:
+
+- **Slipway**, which represents build-oriented workflow
+- **Voyage**, which represents deployment-oriented workflow

docs/concepts/index.md

@@ -0,0 +1,11 @@
+# Concepts
+
+This section introduces the main concepts in Koptan.
+
+Koptan centers around three resource groups:
+
+- **Apps**
+- **Slipway**
+- **Voyage**
+
+Together, these resources provide a structured way to define, build, and manage applications in Kubernetes.

docs/concepts/slipway.md

@@ -0,0 +1,29 @@
+# Slipway
+
+`Slipway` is a Koptan resource associated with build-oriented workflow.
+
+## Purpose
+
+Slipway represents the part of the operator responsible for preparing or building application artifacts.
+
+In practical terms, this may include operations such as:
+
+- fetching source code
+- preparing build context
+- running language-specific build logic
+- producing deployable output
+
+## Implementation Clues in the Repository
+
+Relevant files include:
+
+- `api/v1alpha/slipway_types.go`
+- `internal/controller/slipway_controller.go`
+- `internal/controller/slipway_build.go`
+
+## Relationship to Other Resources
+
+Slipway works alongside:
+
+- **App** resources, which describe the application
+- **Voyage**, which represents the runtime or deployment stage

docs/concepts/voyage.md

@@ -0,0 +1,28 @@
+# Voyage
+
+`Voyage` is a Koptan resource associated with deployment-oriented workflow.
+
+## Purpose
+
+Voyage represents the stage where an application moves from build output into a running state on Kubernetes.
+
+Depending on how the operator evolves, this may include concerns such as:
+
+- rollout
+- runtime configuration
+- deployment reconciliation
+- lifecycle management
+
+## Implementation Clues in the Repository
+
+Relevant files include:
+
+- `api/v1alpha/voyage_types.go`
+- `internal/controller/voyage_controller.go`
+
+## Relationship to Other Resources
+
+Voyage works with:
+
+- **App** resources, which define the application
+- **Slipway**, which handles build-oriented workflow

docs/examples/app.md

@@ -0,0 +1,47 @@
+# App Example
+
+An App resource defines the source code repository for an application.
+
+Koptan currently supports multiple app kinds, including:
+
+- `GoApp`
+- `JavaApp`
+- `DotnetApp`
+
+The only required field is the source repository. The examples below show minimal definitions for each app type.
+
+=== "GoApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: GoApp
+    metadata:
+      name: feedme
+    spec:
+      source:
+        repo: https://github.com/example/feedme
+    ```
+
+=== "JavaApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: JavaApp
+    metadata:
+      name: orders-service
+    spec:
+      source:
+        repo: https://github.com/example/orders-service
+    ```
+
+=== "DotnetApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: DotnetApp
+    metadata:
+      name: payments-service
+    spec:
+      source:
+        repo: https://github.com/example/payments-service
+    ```

docs/examples/index.md

@@ -0,0 +1,15 @@
+# Examples
+
+This section provides simple examples of the three main Koptan resources:
+
+- **App**: defines the application source repository
+- **Slipway**: connects an app to the build pipeline
+- **Voyage**: deploys the built application
+
+A typical Koptan workflow looks like this:
+
+1. Create an App resource
+2. Create a Slipway that references the App
+3. Create a Voyage that references the Slipway
+
+Use the pages in this section to see minimal working examples for each resource.

docs/examples/slipway.md

@@ -0,0 +1,51 @@
+# Slipway Example
+
+A Slipway connects an application to the build pipeline.
+
+It references an existing App using `name` and `kind`.
+
+## Examples
+
+=== "GoApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Slipway
+    metadata:
+      name: feedme
+    spec:
+      appRef:
+        name: feedme
+        kind: GoApp
+    ```
+
+=== "JavaApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Slipway
+    metadata:
+      name: orders-service
+    spec:
+      appRef:
+        name: orders-service
+        kind: JavaApp
+    ```
+
+=== "DotnetApp"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Slipway
+    metadata:
+      name: payments-service
+    spec:
+      appRef:
+        name: payments-service
+        kind: DotnetApp
+    ```
+
+## Apply a Slipway
+
+```bash
+kubectl apply -f slipway.yaml

docs/examples/voyage.md

@@ -0,0 +1,69 @@
+
+---
+
+# 📄 `docs/examples/voyage.md`
+
+```md
+# Voyage Example
+
+A Voyage deploys an application using a Slipway.
+
+It defines how the application runs inside the cluster.
+
+## Examples
+
+=== "Minimal"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Voyage
+    metadata:
+      name: feedme
+    spec:
+      slipwayRef:
+        name: feedme
+      port: 8080
+    ```
+
+=== "With Replicas & Env"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Voyage
+    metadata:
+      name: feedme
+    spec:
+      slipwayRef:
+        name: feedme
+      port: 8080
+      replicas: 2
+      env:
+        - name: ENV
+          value: production
+        - name: LOG_LEVEL
+          value: info
+    ```
+
+=== "With Health Check"
+
+    ```yaml
+    apiVersion: koptan.felukka.org/v1alpha
+    kind: Voyage
+    metadata:
+      name: feedme
+    spec:
+      slipwayRef:
+        name: feedme
+      port: 8080
+      replicas: 2
+      healthCheck:
+        path: /health
+        port: 8080
+        initialDelaySeconds: 10
+        periodSeconds: 5
+    ```
+
+## Apply a Voyage
+
+```bash
+kubectl apply -f voyage.yaml

docs/getting-started/index.md

@@ -0,0 +1,10 @@
+# Getting Started
+
+This section explains how to install Koptan and begin using its custom resources.
+
+It is intended for first-time users who want to:
+
+- install the operator
+- verify the CRDs are available
+- create an initial App resource
+- understand the basic usage flow

docs/getting-started/installation.md

@@ -0,0 +1,20 @@
+# Installation
+
+Koptan is installed as a Kubernetes operator.
+
+## Prerequisites
+
+Before installing Koptan, make sure you have:
+
+- a Kubernetes cluster
+- `kubectl` configured for that cluster
+- permissions to install CRDs and controller resources
+
+## Install the CRDs
+
+You can install the CRDs using the manifests under `config/crd`.
+
+Example:
+
+```bash
+kubectl apply -k config/crd

docs/getting-started/quickstart.md

@@ -0,0 +1,24 @@
+
+# Quickstart
+
+This page shows a minimal example of using Koptan.
+
+## Step 1: Install the Operator
+
+Make sure Koptan and its CRDs are installed.
+
+See the Installation page for details.
+
+## Step 2: Create an App Resource
+
+Koptan supports multiple application resource types, including `GoApp`, `DotnetApp`, and `JavaApp`.
+
+A minimal example is shown below:
+
+```yaml
+apiVersion: koptan.felukka.sh/v1alpha1
+kind: GoApp
+metadata:
+  name: example-goapp
+spec:
+  {}