Skip to content

docs(development): add Helm chart development principles #418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kvaps wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(development): add Helm chart development principles #418

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions content/en/docs/v1/development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,34 @@ You can use bitnami's [readme-generator](https://github.com/bitnami/readme-gener

Just install it as `readme-generator` binary in your system and run generation using `make generate` command.

## Helm Chart Development Principles

The package structure and development workflow in Cozystack are guided by the following principles:

### Easy to update upstream charts

The original upstream chart must be easy to update, override, and modify. We use the umbrella chart pattern — upstream charts live in the `./charts` directory and are vendored as-is. Customizations go into `values.yaml` overrides and additional `templates/`, while structural changes to the upstream chart are applied via `patches/`. This separation ensures that updating to a new upstream version is straightforward: run `make update`, review the diff, and re-apply patches if needed.

### Local-first artifacts

Patches and container images are stored locally and are part of the package. The `patches/` directory holds any modifications to the upstream chart, and the `images/` directory contains Dockerfiles for building all required images. This ensures full reproducibility — everything needed to build and deploy the package is self-contained within the repository.

{{% alert color="info" %}}
Currently, not all packages build their images locally — some still reference externally-built images. We are actively working toward fully local image builds to achieve complete self-containment and reproducibility.
{{% /alert %}}

### Local development and testing workflow

Every package must be easy to update and test locally against a real cluster, without relying on CI. The standard `make` targets (`make image`, `make diff`, `make apply`) provide a fast feedback loop: build images, compare rendered manifests against the live cluster, and apply changes — all from a developer's workstation.

### No external dependencies

Packages must not depend on external resources at runtime. All charts, images, and patches are vendored into the repository. This guarantees that builds and deployments are deterministic and do not break due to upstream registry outages, removed tags, or network issues.

{{% alert color="info" %}}
As noted above, full image self-containment is a work in progress. Some packages still pull images from external registries — this is a known gap that we plan to close as capacity allows.
{{% /alert %}}
Comment on lines +171 to +197
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for all occurrences of "Helm Chart Development Principles" in the file
rg -n "##\s+Helm Chart Development Principles" content/en/docs/v1/development.md

# Also search for similar headings that might indicate duplication
rg -n -C3 "Helm Chart Development" content/en/docs/v1/development.md

# Get total line count to understand file size
wc -l content/en/docs/v1/development.md

Repository: cozystack/website

Length of output: 418

Remove duplicate alert — the two info boxes convey redundant information.

The section "Helm Chart Development Principles" appears only once in the file (not duplicated). However, the two info alerts within this section (lines 183-185 and 195-197) both communicate the same message: that some packages still reference external images rather than building locally. Consolidate these into a single alert to improve clarity and avoid reader confusion.

🤖 Prompt for AI Agents 
In `@content/en/docs/v1/development.md` around lines 171 - 197, Consolidate the
two duplicate info alerts (the two {{% alert color="info" %}} ... {{% /alert %}}
blocks) under the "Helm Chart Development Principles" section into a single
alert that contains the combined message about some packages still referencing
externally-built images and the plan to fully local-build images; remove the
second alert block and keep one clear alert placed near the "Local-first
artifacts" or "No external dependencies" paragraphs so the information remains
visible and non-redundant.


Comment on lines +195 to +198
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This alert box and the following blank line are redundant. The information about image self-containment being a work in progress is already mentioned in the alert under the 'Local-first artifacts' section (lines 183-185). Removing this repeated note will make the document more concise.

## Development

### Buildx configuration
Expand Down