Add Kubernetes deployment docs and refactor Claude skills#362
Merged
t0mdavid-m merged 15 commits intomainfrom Apr 20, 2026
Merged
Add Kubernetes deployment docs and refactor Claude skills#362t0mdavid-m merged 15 commits intomainfrom
t0mdavid-m merged 15 commits intomainfrom
Conversation
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.
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.
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.
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.
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.
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).
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.
The workflow does not block merges directly — it produces a check status that a branch-protection rule can gate on. Make the preconditions explicit.
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.
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.
📝 WalkthroughWalkthroughThis PR reorganizes deployment documentation by splitting monolithic configuration steps into focused guides for app settings, Docker Compose deployment, and Kubernetes deployment. It introduces new documentation pages for Kubernetes deployment architecture and updates the documentation navigation UI to surface the new Kubernetes guide. Kustomize template patches are removed, presuming dynamic configuration via the new deployment guides. Changes
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/configure-app-settings.md:
- Around line 21-26: The example in this doc hardcodes "online_deployment":
false which can lead to deploying online/both modes with local-only settings;
update the guidance and example so the "online_deployment" flag is explicitly
tied to the requested deployment mode (local/online/both), e.g., instruct users
to set "online_deployment": true for online or both deployments and to adjust
the nested max_threads keys in settings.json (local vs online) accordingly, and
update the sample block that contains "online_deployment" and the explanatory
text around "app-name", "github-user", "repository-name", "version",
"enable_workspaces", and "max_threads" to make this mapping clear.
In @.claude/skills/configure-docker-compose-deployment.md:
- Around line 13-26: Update the example Docker Compose snippet so the service
and volume placeholders consistently use the repository name instead of
"your-app-name"; specifically replace the service identifier "your-app-name" and
the volume name "workspaces-your-repo-name" with the repo-based placeholder
(e.g., a single consistent repository-name placeholder) and update any
corresponding references in the YAML (service key, ports block, and volumes
mapping) so the service key and volume key match the same repo-based identifier.
In `@docs/kubernetes-deployment.md`:
- Around line 180-190: Add a pre-deploy manifest render check by running
"kubectl kustomize k8s/overlays/<your-app-name>/" before the existing "kubectl
apply -k k8s/overlays/<your-app-name>/" step so users can catch patch/image/name
errors locally; update the flow so the rendered-manifest step appears directly
before the apply step and increment the following "Verify" section header
(change Step 6 to Step 7) that contains "kubectl -n openms get pods -l
app=<your-app-name>" and "kubectl -n openms rollout status
deployment/<your-app-name>-streamlit --timeout=120s".
- Line 20: The markdown code fence used for the ASCII architecture diagram
should be labeled with a language to satisfy markdownlint; update the
architecture code fence from an unlabeled block to a text-labeled block by
changing the opening fence to ```text so the ASCII diagram is treated as plain
text.
- Line 210: Update the docs to stop recommending passing GITHUB_TOKEN as a
Docker build-arg and instead instruct using BuildKit secrets; replace the
sentence referencing the workflow's `GITHUB_TOKEN` being passed as a build
argument with guidance to use BuildKit secret mounts (e.g., `--secret
id=github_token,src=/run/secrets/github_token` and `RUN
--mount=type=secret,id=github_token ...`) for in-image private-resource access
and GHCR login, and mention that this prevents credentials from appearing in
image history and keeps them out of build metadata.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 06f113dc-278c-461a-a4fe-e14b730c9492
📒 Files selected for processing (8)
.claude/skills/configure-app-settings.md.claude/skills/configure-docker-compose-deployment.md.claude/skills/configure-k8s-deployment.mdcontent/documentation.pydocs/deployment.mddocs/kubernetes-deployment.mdk8s/overlays/template-app/kustomization.yamltest_gui.py
💤 Files with no reviewable changes (1)
- k8s/overlays/template-app/kustomization.yaml
Comment on lines
+21
to
+26
| "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. |
There was a problem hiding this comment.
Tie online_deployment to the requested deployment mode.
The skill asks for deployment mode, but the example hardcodes "online_deployment": false. Add explicit guidance so online/both deployments do not accidentally get local-only settings.
Proposed clarification
- 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.
+ Set `online_deployment` from the requested deployment mode (`true` for online/both, `false` for local-only). 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.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "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. | |
| "online_deployment": false, | |
| "enable_workspaces": true | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/skills/configure-app-settings.md around lines 21 - 26, The example
in this doc hardcodes "online_deployment": false which can lead to deploying
online/both modes with local-only settings; update the guidance and example so
the "online_deployment" flag is explicitly tied to the requested deployment mode
(local/online/both), e.g., instruct users to set "online_deployment": true for
online or both deployments and to adjust the nested max_threads keys in
settings.json (local vs online) accordingly, and update the sample block that
contains "online_deployment" and the explanatory text around "app-name",
"github-user", "repository-name", "version", "enable_workspaces", and
"max_threads" to make this mapping clear.
Comment on lines
+13
to
+26
| ```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. |
There was a problem hiding this comment.
Make the service-name placeholder match the naming rule.
Line 26 says the service and volume names should use the repository name, but the example service uses your-app-name. This can lead the skill to generate mixed Compose identifiers.
Proposed documentation fix
services:
- your-app-name:
+ your-repo-name:
build: .
ports:
- "8501:8501"
volumes:
- workspaces-your-repo-name:/workspaces-your-repo-name📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ```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. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/skills/configure-docker-compose-deployment.md around lines 13 - 26,
Update the example Docker Compose snippet so the service and volume placeholders
consistently use the repository name instead of "your-app-name"; specifically
replace the service identifier "your-app-name" and the volume name
"workspaces-your-repo-name" with the repo-based placeholder (e.g., a single
consistent repository-name placeholder) and update any corresponding references
in the YAML (service key, ports block, and volumes mapping) so the service key
and volume key match the same repo-based identifier.
|
|
||
| ## 2. Architecture | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add a language to the architecture code fence.
markdownlint flags this fence; use text for the ASCII diagram.
Proposed fix
-```
+```text🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 20-20: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/kubernetes-deployment.md` at line 20, The markdown code fence used for
the ASCII architecture diagram should be labeled with a language to satisfy
markdownlint; update the architecture code fence from an unlabeled block to a
text-labeled block by changing the opening fence to ```text so the ASCII diagram
is treated as plain text.
Comment on lines
+180
to
+190
| ### Step 5 — Deploy | ||
|
|
||
| ```bash | ||
| kubectl apply -k k8s/overlays/<your-app-name>/ | ||
| ``` | ||
|
|
||
| ### Step 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 |
There was a problem hiding this comment.
Add render validation before applying the overlay.
The guide jumps straight to kubectl apply -k; include kubectl kustomize first so users catch patch/image/name errors before touching the cluster.
Proposed flow update
-### Step 5 — Deploy
+### Step 5 — Validate
+
+```bash
+kubectl kustomize k8s/overlays/<your-app-name>/
+```
+
+This should print the rendered manifests with no errors.
+
+### Step 6 — Deploy
```bash
kubectl apply -k k8s/overlays/<your-app-name>/-### Step 6 — Verify
+### Step 7 — Verify
</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
### Step 5 — Validate
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/kubernetes-deployment.md` around lines 180 - 190, Add a pre-deploy
manifest render check by running "kubectl kustomize
k8s/overlays/<your-app-name>/" before the existing "kubectl apply -k
k8s/overlays/<your-app-name>/" step so users can catch patch/image/name errors
locally; update the flow so the rendered-manifest step appears directly before
the apply step and increment the following "Verify" section header (change Step
6 to Step 7) that contains "kubectl -n openms get pods -l app=<your-app-name>"
and "kubectl -n openms rollout status deployment/<your-app-name>-streamlit
--timeout=120s".
| - **Image name:** `ghcr.io/${{ github.repository }}`. | ||
| - **Dockerfile:** `Dockerfile` (full build with TOPP tools). | ||
| - **Tags:** branch name, semver (when a tag is pushed), short commit SHA. | ||
| - **Auth:** uses the workflow's `GITHUB_TOKEN` for GHCR login; also passes it as a build argument for in-image private-resource access. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect workflow usage around Docker build/push and token handling.
rg -n -C3 --iglob '*.yml' --iglob '*.yaml' \
'(docker/build-push-action|build-args|GITHUB_TOKEN|secrets:)' .github || true
# Inspect Dockerfiles for token ARG/ENV usage or BuildKit secret mounts.
rg -n -C3 --iglob 'Dockerfile*' \
'(^\s*(ARG|ENV)\s+GITHUB_TOKEN\b|GITHUB_TOKEN|--mount=type=secret)' . || trueRepository: OpenMS/streamlit-template
Length of output: 5111
Update documentation to recommend BuildKit secrets instead of build arguments for passing credentials.
The workflow currently passes GITHUB_TOKEN via Docker build arguments (visible in image history and not secret-safe). Recommend updating the documentation to specify BuildKit secrets (--mount=type=secret) as the secure approach for private resource access during builds.
Proposed documentation wording
-- **Auth:** uses the workflow's `GITHUB_TOKEN` for GHCR login; also passes it as a build argument for in-image private-resource access.
+- **Auth:** uses the workflow's `GITHUB_TOKEN` for GHCR login. If private resources are needed during the image build, pass credentials via BuildKit secrets rather than Docker build arguments.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Auth:** uses the workflow's `GITHUB_TOKEN` for GHCR login; also passes it as a build argument for in-image private-resource access. | |
| - **Auth:** uses the workflow's `GITHUB_TOKEN` for GHCR login. If private resources are needed during the image build, pass credentials via BuildKit secrets rather than Docker build arguments. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/kubernetes-deployment.md` at line 210, Update the docs to stop
recommending passing GITHUB_TOKEN as a Docker build-arg and instead instruct
using BuildKit secrets; replace the sentence referencing the workflow's
`GITHUB_TOKEN` being passed as a build argument with guidance to use BuildKit
secret mounts (e.g., `--secret id=github_token,src=/run/secrets/github_token`
and `RUN --mount=type=secret,id=github_token ...`) for in-image private-resource
access and GHCR login, and mention that this prevents credentials from appearing
in image history and keeps them out of build metadata.
This was referenced Apr 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/kubernetes-deployment.md— 5-section reference (overview, architecture with ASCII diagram, per-manifest reference, fork-and-deploy guide, CI/CD pipeline). Registered incontent/documentation.pyso it surfaces as a Streamlit Documentation page.configure-deploymentClaude skill into three focused skills:configure-app-settings(shared app metadata, Dockerfile, README),configure-docker-compose-deployment(docker-compose.yml, cleanup script),configure-k8s-deployment(overlay creation, kubectl apply). The original was renamed viagit mvfirst sogit log --followtraces the docker-compose history.k8s/overlays/template-app/kustomization.yamlwith the production cluster's working version — drop two stale patches (one targeting a Deployment with an Ingress-shaped JSON path, one duplicating the IngressRoute service-name patch).docs/deployment.mdto the new K8s page via a short preamble.Test Plan
kubectl kustomize k8s/overlays/template-app/succeeds; rendered output has the expected Redis URL, hostname, and service-name substitutions.pytest tests/— 28 pass.pytest test_gui.py -k documentation— 8 pass (including the new "Developers Guide: Kubernetes Deployment" smoke test).streamlit run app.py→ Documentation → "Developers Guide: Kubernetes Deployment" — confirm ASCII diagram renders as monospace, tables + code blocks render, no stray backslashes or broken inline code.## Docker Composeheading + existing body all render.k8s-manifests-ci.ymlgreen (kubeconform + kustomize build + kind integration test with both Dockerfile variants).Notes
test_gui.py::test_launch[content/raw_data_viewer.py]) is caused by an unrelated uncommitted modification insrc/view.pythat predates this branch. Not caused by these changes.01cf85afsettings.json key-field inconsistency,7c7556bbnested-backtick rendering bug,bd832588PR-blocking nuance) resolve issues surfaced in inline code review.Summary by CodeRabbit
Documentation
New Features