diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index 4fb3d5d..0000000 --- a/.github/dependabot.yml +++ /dev/null @@ -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" diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b52bcdc --- /dev/null +++ b/CLAUDE.md @@ -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 +helm template --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/.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-.yml` (copy an existing one, e.g. `publish-outline.yml`) — it triggers on pushes to `/**` 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: +up` (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 }}-` (e.g. `...-deployment`, `...-service`, `...-secret`). +- Image tags come from `{{ .Chart.AppVersion }}`. +- Secrets are 1Password `OnePasswordItem` CRs: values expose `secrets.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---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 `.sfs.yaml` template instead of a deployment. +- No chart has dependencies; `charts/` directories are empty. diff --git a/README.md b/README.md index 853d778..1081bc1 100644 --- a/README.md +++ b/README.md @@ -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: +up` (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-.yml` — one thin workflow per chart; triggers on any push touching `/**` (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 `/` and replace every `xxx` placeholder: template file names (`xxx.deployment.yaml` → `.deployment.yaml`), `Chart.yaml`, the `values.yaml` keys, and the `.Values.xxx.*` references inside the templates. +2. Add `.github/workflows/publish-.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 +helm template --set ingress.domain=example.com --set ingress.clusterIssuer=letsencrypt +``` + +(required values vary per chart) + +## Chart conventions + +- Resources are named `{{ .Release.Name }}-{{ .Chart.Name }}-`; template files are named `..yaml` (StatefulSets use `.sfs.yaml`). +- Image tags come from `{{ .Chart.AppVersion }}`. +- Secrets are **1Password `OnePasswordItem` CRs**: values expose `secrets.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---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).