Add Kubernetes deployment docs and refactor Claude skills (#362)

* Remove stale patches from template-app overlay

The Deployment/streamlit patch with Ingress-shaped path /spec/rules/0/host
never applied and produced a silent no-op. The duplicate IngressRoute
service-name patch was redundant with the first IngressRoute patch block.
This brings the on-disk overlay in line with the production cluster's
running version.

* Rename configure-deployment skill to configure-docker-compose-deployment

First step of splitting the skill into three focused skills
(configure-app-settings, configure-docker-compose-deployment,
configure-k8s-deployment). Rename is in its own commit so
git log --follow traces the docker-compose content cleanly.

* Scope docker-compose skill to docker-compose-only

Removes app-level content (settings.json, Dockerfile choice, production
app examples) that will live in configure-app-settings. Adds a
prerequisite note pointing to configure-app-settings.

* Add configure-app-settings skill

Covers app-level configuration (settings.json, Dockerfile choice,
README, dependencies) shared by every deployment mode. Prerequisite
for configure-docker-compose-deployment and configure-k8s-deployment.

* Fix settings.json key-field list inconsistency

The Key fields prose listed max_threads (not in the JSON sample) and
omitted enable_workspaces (which is in the sample). Align the prose
with the sample and describe max_threads separately since it is a
nested object rather than a flat field.

* Add configure-k8s-deployment skill

New skill walking through Kustomize overlay creation and kubectl apply
for deploying a forked app to Kubernetes. Patch list reflects the
three-patch canonical shape (IngressRoute match + service, streamlit
Redis URL, rq-worker Redis URL).

* Fix inline-code rendering in k8s skill

The Host(`...`) escape syntax produced literal backslashes that
broke the inline-code span when rendered by markdown parsers. Rewrite
as Host(...) without nested backticks so the span renders cleanly.

* Add K8s deployment doc — overview and architecture sections

* Add K8s deployment doc — manifest reference section

* Add K8s deployment doc — fork-and-deploy guide

* Add K8s deployment doc — CI/CD pipeline section

* Clarify PR-blocking behavior depends on branch protection

The workflow does not block merges directly — it produces a check
status that a branch-protection rule can gate on. Make the
preconditions explicit.

* Register Kubernetes Deployment page in Streamlit documentation

* Cross-link docs/deployment.md to Kubernetes deployment page

Adds a preamble listing both deployment paths and introduces a
## Docker Compose heading above the existing content. The existing
docker-compose content is preserved verbatim.

* Add smoke test for Kubernetes Deployment documentation page

Extends the parametrized test_documentation cases to cover the new
Documentation page added by this branch, closing the gap where it
was the only selectbox entry without test coverage.

Author: t0mdavid-m

.claude/skills/configure-deployment.md .claude/skills/configure-app-settings.md.claude/skills/configure-deployment.md renamed to .claude/skills/configure-app-settings.md

@@ -1,6 +1,6 @@
-# Configure Deployment
+# Configure App Settings
 
-Set up Docker, settings, and CI/CD configuration for a new or forked app.
+Set up app-level configuration (settings, Dockerfile, README) for a new or forked OpenMS streamlit app. Run before `configure-docker-compose-deployment` or `configure-k8s-deployment`.
 
 ## Instructions
 
@@ -12,18 +12,18 @@ Set up Docker, settings, and CI/CD configuration for a new or forked app.
 
 2. **Update `settings.json`**:
 
-```json
-{
-    "app-name": "Your App Name",
-    "github-user": "YourGitHubUser",
-    "repository-name": "your-repo-name",
-    "version": "0.1.0",
-    "online_deployment": false,
-    "enable_workspaces": true
-}
-```
+    ```json
+    {
+        "app-name": "Your App Name",
+        "github-user": "YourGitHubUser",
+        "repository-name": "your-repo-name",
+        "version": "0.1.0",
+        "online_deployment": false,
+        "enable_workspaces": true
+    }
+    ```
 
-Key fields: `app-name`, `github-user`, `repository-name`, `version`, `online_deployment`, `max_threads`.
+    Key fields: `app-name`, `github-user`, `repository-name`, `version`, `online_deployment`, `enable_workspaces`. `max_threads` (a nested object with `local`/`online` keys in `settings.json`) caps worker parallelism — tune it if your cluster or host has specific CPU constraints.
 
 3. **Choose and update Dockerfile**:
 
@@ -36,30 +36,7 @@ Key fields: `app-name`, `github-user`, `repository-name`, `version`, `online_dep
      - `GITHUB_USER` and `GITHUB_REPO` environment variables
      - Python dependencies in `requirements.txt`
 
-4. **Update `docker-compose.yml`**:
-
-```yaml
-services:
-  your-app-name:
-    build: .
-    ports:
-      - "8501:8501"
-    volumes:
-      - workspaces-your-repo-name:/workspaces-your-repo-name
-
-volumes:
-  workspaces-your-repo-name:
-```
-
-Service name and volume name should use the repository name.
-
-5. **Update `clean-up-workspaces.py`**:
-
-```python
-workspaces_directory = Path("/workspaces-your-repo-name")
-```
-
-6. **Update `README.md`** with the new app name, description, and instructions.
+4. **Update `README.md`** with the new app name, description, and instructions.
 
 ## Dockerfile Decision Guide
 
@@ -72,11 +49,8 @@ workspaces_directory = Path("/workspaces-your-repo-name")
 ## Reference Files
 
 - App settings: `settings.json`
-- Docker: `Dockerfile`, `Dockerfile_simple`, `docker-compose.yml`
+- Docker: `Dockerfile`, `Dockerfile_simple`
 - Build docs: `docs/build_app.md`
-- Deployment docs: `docs/deployment.md`
-- CI/CD: `.github/workflows/` (Docker build, Windows exe, linting, tests)
-- Workspace cleanup: `clean-up-workspaces.py`
 
 ## Real-World Examples
 
@@ -87,8 +61,10 @@ workspaces_directory = Path("/workspaces-your-repo-name")
 ## Checklist
 
 - [ ] `settings.json` updated with app name, GitHub user/repo, version
-- [ ] Correct Dockerfile chosen and configured (GITHUB_USER, GITHUB_REPO)
-- [ ] `docker-compose.yml` updated with service name and volume
-- [ ] `clean-up-workspaces.py` updated with workspace directory path
+- [ ] Correct Dockerfile chosen and configured (`GITHUB_USER`, `GITHUB_REPO`)
 - [ ] `requirements.txt` or `environment.yml` updated with dependencies
 - [ ] `README.md` updated
+
+## Next Steps
+
+Run `configure-docker-compose-deployment` and/or `configure-k8s-deployment` to set up the deployment path(s).

.claude/skills/configure-docker-compose-deployment.md

@@ -0,0 +1,51 @@
+# Configure Docker Compose Deployment
+
+Set up docker-compose-specific configuration for a new or forked OpenMS streamlit app.
+
+## Prerequisite
+
+Run `configure-app-settings` first. This skill assumes `settings.json`, the Dockerfile, and app metadata (app name, GitHub user/repo, README) are already configured.
+
+## Instructions
+
+1. **Update `docker-compose.yml`**:
+
+    ```yaml
+    services:
+      your-app-name:
+        build: .
+        ports:
+          - "8501:8501"
+        volumes:
+          - workspaces-your-repo-name:/workspaces-your-repo-name
+
+    volumes:
+      workspaces-your-repo-name:
+    ```
+
+    Service name and volume name should use the repository name.
+
+2. **Update `clean-up-workspaces.py`**:
+
+    ```python
+    workspaces_directory = Path("/workspaces-your-repo-name")
+    ```
+
+3. **Build and run**:
+
+    ```bash
+    docker-compose up --build -d
+    ```
+
+## Reference Files
+
+- Docker Compose: `docker-compose.yml`
+- Workspace cleanup: `clean-up-workspaces.py`
+- Full reference: see the "Developers Guide: Deployment" Documentation page in the running Streamlit app.
+
+## Checklist
+
+- [ ] `docker-compose.yml` updated with service name and volume
+- [ ] `clean-up-workspaces.py` updated with workspace directory path
+- [ ] Successfully builds and starts with `docker-compose up --build -d`
+- [ ] App accessible at http://localhost:8501

.claude/skills/configure-k8s-deployment.md

@@ -0,0 +1,81 @@
+# Configure Kubernetes Deployment
+
+Create a Kustomize overlay for deploying a forked OpenMS streamlit app to Kubernetes.
+
+## Prerequisite
+
+Run `configure-app-settings` first. This skill assumes `settings.json`, the Dockerfile, and app metadata are already configured.
+
+## Cluster Prerequisites
+
+- `kubectl` configured for the target cluster
+- A storage class that supports `ReadWriteOnce` volumes (default: `cinder-csi` for de.NBI / OpenStack)
+- An ingress controller (default: Traefik; nginx also supported via the base `Ingress` resource)
+- Read access to GHCR for pulling the app image
+- A DNS record pointing to the cluster's ingress load balancer
+
+## Instructions
+
+1. **Let CI build and push the image.**
+
+   Push your changes to `main` or create a tag. The workflow `.github/workflows/build-and-push-image.yml` publishes the image to `ghcr.io/<your-org>/<your-repo>:<tag>`.
+
+2. **Copy the template overlay.**
+
+    ```bash
+    cp -r k8s/overlays/template-app k8s/overlays/<your-app-name>
+    ```
+
+3. **Edit `k8s/overlays/<your-app-name>/kustomization.yaml`**:
+
+   - Change `namePrefix` from `template-app-` to `<your-app-name>-`
+   - Change `commonLabels.app` from `template-app` to `<your-app-name>`
+   - Change `images[0].newName` to `ghcr.io/<your-org>/<your-repo>`
+   - In the IngressRoute patch, update:
+     - the `Host(...)` match — change the quoted hostname to your own
+     - the service name reference from `template-app-streamlit` to `<your-app-name>-streamlit`
+   - In both Deployment patches (`streamlit` and `rq-worker`), update the Redis URL from `redis://template-app-redis:6379/0` to `redis://<your-app-name>-redis:6379/0`
+
+   The overlay leaves the nginx `Ingress` unpatched because production deployments use Traefik. If you are deploying to an nginx-only cluster, substitute an Ingress host patch for the IngressRoute patch.
+
+4. **Validate the overlay builds.**
+
+    ```bash
+    kubectl kustomize k8s/overlays/<your-app-name>/
+    ```
+
+    Should print the rendered manifests with no errors.
+
+5. **Deploy.**
+
+    ```bash
+    kubectl apply -k k8s/overlays/<your-app-name>/
+    ```
+
+6. **Verify.**
+
+    ```bash
+    kubectl -n openms get pods -l app=<your-app-name>
+    kubectl -n openms rollout status deployment/<your-app-name>-streamlit --timeout=120s
+    ```
+
+    Smoke-test the ingress URL in a browser.
+
+## Reference Files
+
+- Overlay template: `k8s/overlays/template-app/kustomization.yaml`
+- Base manifests: `k8s/base/*.yaml`
+- CI: `.github/workflows/build-and-push-image.yml`, `.github/workflows/k8s-manifests-ci.yml`
+- Full reference: see the "Developers Guide: Kubernetes Deployment" Documentation page in the running Streamlit app.
+
+## Checklist
+
+- [ ] Image built and pushed to GHCR (via CI or manual push to `main`/tag)
+- [ ] Overlay copied to `k8s/overlays/<your-app-name>/`
+- [ ] `namePrefix`, `commonLabels.app`, `images[0].newName` updated
+- [ ] IngressRoute patch updated (host + service reference)
+- [ ] Redis URL updated in both Deployment patches
+- [ ] `kubectl kustomize` succeeds
+- [ ] `kubectl apply -k` succeeds
+- [ ] All pods Running, `rollout status` succeeds
+- [ ] App accessible via the ingress hostname

content/documentation.py

@@ -17,6 +17,7 @@
     "Developers Guide: TOPP Workflow Framework",
     "Developer Guide: Windows Executables",
     "Developers Guide: Deployment",
+    "Developers Guide: Kubernetes Deployment",
 ]
 page = cols[0].selectbox(
     "**Content**",
@@ -106,4 +107,13 @@
 if page == pages[5]:
     with open(Path("docs", "deployment.md"), "r", encoding="utf-8") as f:
         content = f.read()
-    st.markdown(content) 
+    st.markdown(content)
+
+#############################################################################################
+# Kubernetes Deployment
+#############################################################################################
+
+if page == pages[6]:
+    with open(Path("docs", "kubernetes-deployment.md"), "r", encoding="utf-8") as f:
+        content = f.read()
+    st.markdown(content)

docs/deployment.md

@@ -1,5 +1,16 @@
 # OpenMS streamlit app deployment
 
+OpenMS streamlit apps can be deployed two ways:
+
+- **Kubernetes** — Kustomize manifests under `k8s/` with CI-built images pushed to GHCR. See the "Developers Guide: Kubernetes Deployment" page.
+- **Docker Compose** — described below. Uses the external [OpenMS/streamlit-deployment](https://github.com/OpenMS/streamlit-deployment) repo to aggregate multiple apps as submodules.
+
+If you're using Claude Code, the `configure-app-settings` and `configure-docker-compose-deployment` skills automate the docker-compose path; `configure-app-settings` + `configure-k8s-deployment` automate the Kubernetes path.
+
+---
+
+## Docker Compose
+
 Multiple streamlit apps based on the [OpenMS streamlit template](https://github.com/OpenMS/streamlit-template/) can be deployed together using docker compose.
 
 ## Features