Thanks for helping improve the Appwrite Helm chart.
| Tool | Version | Used by |
|---|---|---|
| Helm | 4.3.x | everything |
chart-testing (ct) |
3.14.x | make lint |
| yamllint | 1.35+ | ct lint |
| helm-docs | 1.14.x | make docs |
| kubeconform | 0.8.x | make kubeconform, make examples |
| yq | 4.x (the Go one) | make images |
| Python | 3 | make schema |
| PHP | 8+ | make env-defaults |
kind, Docker, kubectl |
recent | make kind-up install |
curl, jq |
recent | make smoke, make changes, hack/*.sh |
| actionlint, shellcheck, uv | recent | make lint-actions (only when you change workflows or hack/) |
Install the Helm plugins with make tools. It installs
helm-unittest and
helm-values-schema-json
at the versions pinned in the Makefile.
The chart itself supports Helm 3.18 and later, and CI lints and unit-tests it
with Helm 3 too. Developing needs Helm 4: make tools passes
--verify=false, which Helm 3's helm plugin install doesn't accept. With
Helm 3, install the plugins from git instead:
helm plugin install https://github.com/helm-unittest/helm-unittest --version v1.2.1
helm plugin install https://github.com/losisin/helm-values-schema-json --version v2.6.0Run make help to list every target.
- Change the templates and
charts/appwrite/values.yaml, following the values design. Document every new value with a# --comment directly above it (helm-docs turns these into the chart README), and add# @schemaannotations where the inferred type isn't enough. - Add or update unit tests under
charts/appwrite/tests/, and run them withmake unittest. - Keep the guides and examples in step. When a change affects how people
configure the chart, update the guide in
docs/and the files inexamples/that set those values.make exampleslints every example and validates what it renders. A new example file goes inEXAMPLESin the Makefile (an overlay together with its base files, joined with+, e.g.minimal+aws) and in the table in examples/README.md. - Run
make generate. It refreshesvalues.schema.json, the chartREADME.mdand theartifacthub.io/imagesannotation inChart.yaml. Never edit those by hand: the chart README comes fromREADME.md.gotmpland the comments invalues.yaml. - Run
make test: lint, unit tests, kubeconform, examples and a check that the generated files are current. CI runs the same checks. - For changes to what gets deployed, install the chart on kind (see below).
- Add an entry under
[Unreleased]inCHANGELOG.md, under the Keep a Changelog heading that fits (Added, Changed, Deprecated, Removed, Fixed, Security), one bullet per change. Don't bumpversioninChart.yamlor editartifacthub.io/changes: both happen when a release is cut, as described in RELEASING.md. CI fails a pull request that changescharts/appwrite/without a changelog entry; a maintainer adds theskip-changeloglabel when users won't notice the change (tests, comments, CI). - Open a pull request against
mainand fill in the checklist.
make install installs or upgrades the release appwrite in the namespace
appwrite, labelled to enforce the restricted Pod Security Standard, with
the values files in VALUES (default charts/appwrite/ci/default-values.yaml):
make kind-up # kind cluster "appwrite"
make install helm-test smoke # install, run helm test and hack/smoke.sh
make install VALUES="charts/appwrite/ci/default-values.yaml my-values.yaml"
make kind-downFunctions and Sites are on by default, on the built-in object storage. To build and execute a function as the nightly workflow does:
make install VALUES=charts/appwrite/ci/full-values.yaml
hack/functions-smoke.sh appwrite appwrite node-22The scenarios CI installs are the charts/appwrite/ci/*-values.yaml files.
| Workflow | When | What |
|---|---|---|
| Lint and test | every pull request and push to main |
ct lint and helm lint --strict for every ci/ scenario, unit tests (Helm 3.18 and 4.3), kubeconform, make examples, generated files, artifacthub.io/images, ah lint, a CHANGELOG.md entry for chart changes and make check-changes |
| Install | changes to charts/, hack/, the Makefile or the workflow |
installs on kind per scenario, helm test, hack/smoke.sh, routes through Traefik, an upgrade from the previous Appwrite release, and a second upgrade that must keep credentials and pods; Install result sums up the scenarios |
| Workflow lint | changes to workflows or hack/*.sh |
actionlint, shellcheck and zizmor (make lint-actions locally) |
| Renovate generate | Renovate pull requests that change values.yaml or Chart.yaml |
runs make generate and commits the result, see below |
| Nightly end-to-end | daily | ci/full-values.yaml (every optional component but embedding) with Functions built and executed in the cluster |
| Security scan | daily | Trivy on every image in artifacthub.io/images and on the manifests of every ci/ scenario; code scanning once the repository is public |
| Scorecard | weekly and pushes to main |
OpenSSF Scorecard, once the repository is public |
| Upstream drift | weekly | opens an issue when Appwrite releases a version the chart doesn't ship |
| Release | Chart.yaml changes on main |
see RELEASING.md |
Jobs run on Appwrite's gcrunner
runners: an ephemeral Compute Engine VM per job, picked with
runs-on: gcrunner=<run id>-<job>-<index>/machine=<type> (c3d-standard-8
for the nightly, c3d-standard-4 otherwise). Pull requests from forks ask for
GitHub-hosted runners instead. That isn't a security boundary: a pull request
runs its own copy of the workflow, so a fork can ask for gcrunner, and
gcrunner doesn't check where a job comes from. While the repository is
public, the guard is that a maintainer approves every workflow run from a
fork pull request (Settings → Actions → General → "Require approval for all
external contributors") after reading its workflow changes; never approve a
fork's run that changes runs-on. Release and Scorecard stay on GitHub-hosted
runners: Scorecard only publishes results from them, and the release's
signature and provenance attestation name the runner that built the chart.
Workflows pin every action to a commit SHA (with the version in a comment)
and every tool to a version in env:, which Renovate updates through the
custom managers in renovate.json. A new pinned tool needs a manager there.
Accepted zizmor findings go in .github/zizmor.yml, each with its reason.
Renovate bumps image tags but can't run make generate, so the
Renovate generate workflow
regenerates the schema, the chart README and artifacthub.io/images on its
pull requests and commits them to the branch. It commits with a GitHub App,
because commits pushed with the workflow's own token don't trigger the
checks again. One-time setup, by an organisation owner:
- Create a GitHub App (Organisation settings → Developer settings → GitHub Apps) with no webhook and one repository permission, Contents: Read and write. Install it on this repository only.
- Generate a private key for it.
- In the repository's Actions secrets, set
RENOVATE_HOOK_APP_IDto the App's client ID (its numeric app ID works too) andRENOVATE_HOOK_PRIVATE_KEYto the private key.
Until then the workflow only leaves a notice, and someone runs
make generate on the branch and pushes the result.
The upstream drift workflow opens an
issue when Appwrite has released a version the chart doesn't ship yet,
listing the environment variables that changed (Renovate, once enabled,
also opens a pull request for appVersion). To follow it:
-
Set
appVersionincharts/appwrite/Chart.yaml. Leaveimage.taginvalues.yamlempty: it followsappVersion. -
Run
make env-defaultsto regeneratefiles/env-defaults.yamlfrom the new version'sapp/config/variables.php, and review the diff. New variables may need values or computed settings intemplates/_env.tpl. -
Compare the new version's
docker-compose.ymlwith the chart: image tags of the console, geo, browser and other components, the orchestrator and executor versions, new workers or queues (app/config/workers.php, mirrored by the queue catalog intemplates/workers/_workers.tpland byworkers.queues), and new tasks. -
Check whether the data migration changed (
src/Appwrite/Migration/Migration.php) and update docs/upgrading.md if it did. -
Find what else names the old version, such as the docs, the chart icon URL and the DNS check in the install workflow, with
git grep -n <old version>. Setupgrade-fromin test-install.yaml to the version the chart shipped until now. -
Run
make generate test, then test the upgrade on kind the way CI does:make kind-up helm upgrade --install appwrite charts/appwrite -n appwrite --create-namespace \ -f charts/appwrite/ci/default-values.yaml --set image.tag=<old version> --wait --timeout 15m make install helm-test smoke
-
Add a CHANGELOG entry.
hack/appwrite-e2e.sh runs the PHPUnit e2e suites of
a checkout of appwrite/appwrite
against a release, at the release's Appwrite version:
make kind-up install VALUES="charts/appwrite/ci/full-values.yaml <compute values>"
hack/appwrite-e2e.sh ~/source/appwrite appwrite appwrite tests/e2e/Services/Account
hack/appwrite-e2e.sh ~/source/appwrite appwrite appwrite --filter testCreateUser tests/e2e/Services/UsersIt reconfigures the release for testing (development mode, open console
sign-up, mail and request catchers), so only point it at a throwaway install.
Functions and Sites suites need the runtimes they use in
compute.functionsRuntimes (as charts/appwrite/ci/full-values.yaml sets). Suites that need a fresh instance (the first
organization in Teams), GitHub or Gitea, or ClamAV don't pass against a shared
install.
- One top-level block per service. A datastore the chart can either run or
connect to (
database,redis,clickhouse) has amode:builtindeploys it in the release,externalconnects to the user's own. Settings Appwrite needs either way (name, username, password, pool sizes) sit at the top of the block;externalholds only the address (hostandport, orurl);builtinholds everything about the StatefulSet the chart runs (image, resources, persistence, security contexts, scheduling, metrics). New built-in settings go underbuiltin. Templates get connection settings fromappwrite.db,appwrite.redisandappwrite.clickhouseintemplates/_datastores.tplinstead of branching onmodethemselves. Services Appwrite only connects to (documentsDb,vectorsDb,storage,smtp) are top-level blocks too, not nested underappwrite. - Every credential has the same shape,
{value, secretName, secretKey}:valueis set inline and stored in the chart's Secret (or generated there when the chart runs the service and it's empty),secretNamenames a Secret the user manages and takes precedence overvalue, andsecretKeyis the key in that Secret, defaulting to the key the chart uses in its own (db-password,smtp-password,s3-access-key). Templates read one withappwrite.credentialorappwrite.credential.valueFrom. A new credential goes in the list intemplates/_secrets.tpland in thesecretKeycheck intemplates/_validate.tpl. The core and compute secrets (appwrite.secrets,compute.secrets) keep theirexistingSecret: each is a set of keys in one Secret. - Components take
extraEnv,extraEnvFrom,extraVolumes,extraVolumeMounts,extraInitContainersandextraContainerswhere they make sense, so users can add what the chart doesn't model without forking it. Name new hooks the same way. - Scheduling and pod settings live in
defaults.*and apply to every component; a component's own non-empty value replaces the default (pod annotations and labels are merged over it). A new per-component setting that also makes sense chart-wide goes indefaultstoo and falls back to it through the existing helpers. - Every value has a
# --comment directly above it, written for the chart README: what it does, what empty means, and the Appwrite variable it sets if there is one. values.schema.jsonis generated withnoAdditionalProperties, so typos fail. Add# @schemaannotations for enums, minimums, item types and maps (additionalProperties), and list Kubernetes passthrough fields inhack/schema-postprocess.pyso they accept anything the API does.
Renaming or removing a value breaks existing values files, so do it in steps that tell users what to change:
- Keep the old key working, or at least recognised, for at least one minor
release. The schema rejects unknown keys, so keep a permissive stub for
the old key in
values.schema.json(throughvalues.yamlorhack/schema-postprocess.py, never by hand) so the render gets as far as the message below. - Add the old key to
appwrite.deprecations.renamedintemplates/_deprecations.tplwith what to do instead (for a rename, "renamed tonew.key"), so setting it fails with the old key and that message instead of a generic schema error. Add a unit test that sets the old key. - Add a
### Deprecatedentry toCHANGELOG.mdwhen the old key stops being the documented one, and a### Removedentry in the release that drops the stub and the message. - Add a note for the version to "Version notes" in docs/upgrading.md: the old key, the new one, and an example of the change to a values file.
- Values are camelCase. Prefer maps to lists for things users add to or
override one entry at a time (queues, groups, annotations), so
--setand values merging work. Kubernetes fields that are lists (tolerations,parentRefs, NetworkPolicy rules) stay lists. - Helpers are namespaced
appwrite.*and called withinclude. - One Kubernetes resource per template file, except where resources only make sense together (the orchestrator's ServiceAccount, Role and RoleBinding).
- Pin image tags; never use
latest. - Pods must pass the Kubernetes Pod Security Standard
restrictedprofile unless a component documents why it can't.