Merge pull request #3 from jk-cluster/worktree-init-claude-md
Add repo documentation (CLAUDE.md + README) and remove dependabot config
This commit is contained in:
3 files changed
+107
-18
No files matched your search
@@ -1,17 +0,0 @@
|
||||
# To get started with Dependabot version updates, you'll need to specify which
|
||||
# package ecosystems to update and where the package manifests are located.
|
||||
# Please see the documentation for all configuration options:
|
||||
# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
|
||||
version: 2
|
||||
updates:
|
||||
# Enable version updates for Helm
|
||||
- package-ecosystem: "helm"
|
||||
# Look for a `Chart.yaml` in the `root` directory
|
||||
directory: '/homeassistant'
|
||||
# Check for updates once a week
|
||||
schedule:
|
||||
interval: "daily"
|
||||
- package-ecosystem: "docker"
|
||||
directory: '/homeassistant'
|
||||
schedule:
|
||||
interval: "daily"
|
||||
@@ -0,0 +1,44 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Working on issues — mandatory workflow
|
||||
|
||||
When working on a GitHub issue in this repo, follow this process strictly:
|
||||
|
||||
1. **Plan first, get approval**: Present a plan for how you intend to implement the issue and wait for the user's explicit approval. Do not start implementing before the plan is approved.
|
||||
2. **Implement on a dedicated branch**: After approval, work the issue to completion on its own branch.
|
||||
3. **Open a PR** for the changes when the implementation is done.
|
||||
4. **Wait for the user's review**: The user may request changes as comments on the PR — address those. Do not merge yourself.
|
||||
5. Only after the PR has been **merged by the user** may work on the next issue begin.
|
||||
|
||||
## What this repo is
|
||||
|
||||
A collection of self-made Helm charts, one directory per chart, published to a private OCI registry via GitHub Actions. There is no build system or test suite — validation is done with Helm itself:
|
||||
|
||||
```bash
|
||||
helm lint <chart-name>
|
||||
helm template <chart-name> --set ingress.domain=example.com --set ingress.clusterIssuer=letsencrypt # render locally; required values vary per chart
|
||||
```
|
||||
|
||||
## Creating a new chart
|
||||
|
||||
Copy `template-chart/` and replace every `xxx` placeholder — in file names (`templates/xxx.deployment.yaml` → `templates/<app>.deployment.yaml`), in `Chart.yaml`, and in the `values.yaml` keys and their `.Values.xxx.*` references inside templates. Then wire up CI:
|
||||
|
||||
1. Add `.github/workflows/publish-<chart-name>.yml` (copy an existing one, e.g. `publish-outline.yml`) — it triggers on pushes to `<chart-name>/**` and calls the reusable `publish-helm-chart.yml`.
|
||||
2. Add the chart name to the `chart-name` choice list in `.github/workflows/change-app-version.yml`.
|
||||
|
||||
## Versioning scheme
|
||||
|
||||
`Chart.yaml` versions follow `version: <chart-semver>+up<appVersion>` (e.g. `1.4.0+up1.9.2`), with `appVersion` matching the suffix (dashes in the app version are normalized to dots in the suffix). When changing a chart's templates or values, bump the semver part; when only updating the app version, the `change-app-version.yml` workflow does it (it commits directly to main). Any push touching a chart directory publishes that chart, so the version must be bumped in the same change.
|
||||
|
||||
## Chart conventions (from template-chart)
|
||||
|
||||
- All resources are named `{{ .Release.Name }}-{{ .Chart.Name }}-<kind>` (e.g. `...-deployment`, `...-service`, `...-secret`).
|
||||
- Image tags come from `{{ .Chart.AppVersion }}`.
|
||||
- Secrets are 1Password `OnePasswordItem` CRs: values expose `secrets.<name>SecretRef` holding an `op://` item path; the operator materializes the Kubernetes Secret.
|
||||
- Ingress assumes `ingressClassName: nginx` and cert-manager: `ingress.clusterIssuer` and `ingress.domain` are `required` values, TLS secret named `tls-<release>-<chart>-ingress`.
|
||||
- `env` entries in values support Helm templating — the deployment renders them through `tpl`, and supports `value`, `secretKeyRef`, and `configMapKeyRef` forms.
|
||||
- Hardened defaults: `automountServiceAccountToken: false`, non-root user, `readOnlyRootFilesystem: true`, all capabilities dropped; probes and resource requests/limits always set.
|
||||
- Stateful apps use a StatefulSet in a `<app>.sfs.yaml` template instead of a deployment.
|
||||
- No chart has dependencies; `charts/` directories are empty.
|
||||
@@ -1,2 +1,64 @@
|
||||
# helm-charts
|
||||
Collection of some self-made helm-charts
|
||||
|
||||
Collection of some self-made helm-charts. Each top-level directory is a standalone Helm chart that gets packaged and pushed to a private OCI registry (JK-Registry) via GitHub Actions.
|
||||
|
||||
## Charts
|
||||
|
||||
| Chart | Deploys | Notes |
|
||||
|---|---|---|
|
||||
| `apache-tika` | Apache Tika | Deployment + Service only (no ingress) |
|
||||
| `calibre-web-automated` | Calibre-Web Automated | StatefulSet, extra consume-PVC |
|
||||
| `cyberchef` | CyberChef | Stateless Deployment |
|
||||
| `gotenberg` | Gotenberg | Deployment + Service only (no ingress) |
|
||||
| `homeassistant` | Home Assistant | StatefulSet, has `NOTES.txt` and Helm tests |
|
||||
| `matrix-synapse` | Matrix Synapse | StatefulSet plus an nginx delegation Deployment/Service |
|
||||
| `music-assistant-skill` | Music Assistant Alexa Skill | Uses `_helpers.tpl` (unlike the other charts) |
|
||||
| `outline` | Outline | StatefulSet, separate DB/Redis secrets |
|
||||
| `paperless-ngx` | Paperless-ngx | Largest chart: consume CronJob, SMB-connector PV/PVC, pre/post-consumption scripts ConfigMap |
|
||||
| `patchmon` | PatchMon | Two Deployments (frontend + backend), OIDC secret |
|
||||
| `rallly` | Rallly | Deployment, DB/OIDC/SMTP secrets |
|
||||
| `samba` | Samba | StatefulSet, users secret + config ConfigMap |
|
||||
| `satisfactory` | Satisfactory game server | StatefulSet, no ingress |
|
||||
| `teamspeak-server` | TeamSpeak server | StatefulSet, no ingress |
|
||||
| `template-chart` | — | Scaffold for new charts (placeholder `xxx`), never published |
|
||||
| `urlaubsverwaltung` | Urlaubsverwaltung | Deployment, DB + OIDC secrets |
|
||||
| `voucher-vault` | VoucherVault | StatefulSet, DB + OIDC secrets |
|
||||
| `zipline` | Zipline | StatefulSet, DB secret |
|
||||
|
||||
## Versioning
|
||||
|
||||
`Chart.yaml` uses the scheme `version: <chart-semver>+up<app-version>` (e.g. `1.4.0+up1.9.2`), where `appVersion` matches the `+up` suffix (dashes in the app version are normalized to dots in the suffix, e.g. `0.0.36-beta` → `+up0.0.36.beta`).
|
||||
|
||||
- Bump the **semver part** when the chart itself (templates/values) changes.
|
||||
- The **app version** is bumped via the `Change App-Version` workflow, which rewrites `version:`/`appVersion:` and commits directly to `main`.
|
||||
|
||||
## CI/CD (GitHub Actions)
|
||||
|
||||
- `publish-<chart>.yml` — one thin workflow per chart; triggers on any push touching `<chart>/**` (or manually) and calls the reusable workflow below. **A push to a chart directory on `main` publishes that chart**, so the chart version must be bumped in the same change.
|
||||
- `publish-helm-chart.yml` — reusable workflow: `helm package`, then `helm push` to the private JK-Registry. Registry credentials come from 1Password Connect (`OP_CONNECT_TOKEN` secret, items under `op://GitHub-Actions/`).
|
||||
- `change-app-version.yml` — manually dispatched app-version bump; the chart must be listed in its `chart-name` choice list.
|
||||
|
||||
## Creating a new chart
|
||||
|
||||
1. Copy `template-chart/` to `<chart-name>/` and replace every `xxx` placeholder: template file names (`xxx.deployment.yaml` → `<app>.deployment.yaml`), `Chart.yaml`, the `values.yaml` keys, and the `.Values.xxx.*` references inside the templates.
|
||||
2. Add `.github/workflows/publish-<chart-name>.yml` (copy an existing one, e.g. `publish-outline.yml`).
|
||||
3. Add the chart name to the choice list in `.github/workflows/change-app-version.yml`.
|
||||
|
||||
Validate locally with:
|
||||
|
||||
```bash
|
||||
helm lint <chart-name>
|
||||
helm template <chart-name> --set ingress.domain=example.com --set ingress.clusterIssuer=letsencrypt
|
||||
```
|
||||
|
||||
(required values vary per chart)
|
||||
|
||||
## Chart conventions
|
||||
|
||||
- Resources are named `{{ .Release.Name }}-{{ .Chart.Name }}-<kind>`; template files are named `<app>.<kind>.yaml` (StatefulSets use `.sfs.yaml`).
|
||||
- Image tags come from `{{ .Chart.AppVersion }}`.
|
||||
- Secrets are **1Password `OnePasswordItem` CRs**: values expose `secrets.<name>SecretRef` holding an `op://` item path; the 1Password operator materializes the Kubernetes Secret in-cluster.
|
||||
- Ingress assumes ingress-nginx (`ingressClassName: nginx`) and cert-manager: `ingress.clusterIssuer` and `ingress.domain` are required values; the TLS secret is named `tls-<release>-<chart>-ingress`.
|
||||
- `env` entries in `values.yaml` are rendered through `tpl`, so values may contain Helm templating; `value`, `secretKeyRef` and `configMapKeyRef` forms are supported.
|
||||
- Hardened defaults: `automountServiceAccountToken: false`, non-root user, `readOnlyRootFilesystem: true`, all capabilities dropped, probes and resource requests/limits always set.
|
||||
- Charts have no dependencies (`charts/` directories are empty).
|
||||
Reference in new issue
Block a user