From 59f94e65895646ff4768a09d304912c218bfed4d Mon Sep 17 00:00:00 2001 From: Maicon Berlofa Date: Wed, 1 Apr 2026 12:49:49 -0300 Subject: [PATCH 1/3] doc: add Kubernetes deployment guide using HelmForge Helm chart --- .../docs/advanced/self-hosting/+layout.svelte | 4 + .../platforms/kubernetes/+page.markdoc | 128 ++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc diff --git a/src/routes/docs/advanced/self-hosting/+layout.svelte b/src/routes/docs/advanced/self-hosting/+layout.svelte index 5e5302b7a4..d228ebbdfa 100644 --- a/src/routes/docs/advanced/self-hosting/+layout.svelte +++ b/src/routes/docs/advanced/self-hosting/+layout.svelte @@ -43,6 +43,10 @@ { label: 'Coolify', href: '/docs/advanced/self-hosting/platforms/coolify' + }, + { + label: 'Kubernetes', + href: '/docs/advanced/self-hosting/platforms/kubernetes' } ] }, diff --git a/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc b/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc new file mode 100644 index 0000000000..97ea7e3a54 --- /dev/null +++ b/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc @@ -0,0 +1,128 @@ +--- +layout: article +title: Kubernetes deployment +description: Deploy Appwrite on Kubernetes using the HelmForge community Helm chart. +--- + +Deploy Appwrite on Kubernetes using a community-maintained [Helm chart](https://artifacthub.io/packages/helm/helmforge/appwrite). This chart uses the official `appwrite/appwrite` container image — no custom or repackaged containers. + +{% info title="Community resource" %} +This Helm chart is maintained by [HelmForge](https://helmforge.dev), not by the Appwrite team. For issues related to the chart, open an issue on the [chart repository](https://github.com/helmforgedev/charts). +{% /info %} + +# Prerequisites {% #prerequisites %} + +Before starting, ensure you have: + +- A running Kubernetes cluster (v1.26+) +- [Helm](https://helm.sh/docs/intro/install/) v3 installed +- `kubectl` configured to access your cluster + +# Installation {% #installation %} + +{% section #add-repo step=1 title="Add the Helm repository" %} + +```bash +helm repo add helmforge https://repo.helmforge.dev +helm repo update +``` + +Alternatively, install directly from the OCI registry: + +```bash +helm install appwrite oci://ghcr.io/helmforgedev/helm/appwrite +``` + +{% /section %} + +{% section #install-chart step=2 title="Install Appwrite" %} + +```bash +helm install appwrite helmforge/appwrite +``` + +This installs Appwrite with bundled MariaDB and Redis subcharts. All core services are deployed as separate pods, including the API, Console, Realtime, background workers, and schedulers. + +{% /section %} + +{% section #verify step=3 title="Verify the deployment" %} + +Check that all pods are running: + +```bash +kubectl get pods -l app.kubernetes.io/instance=appwrite +``` + +Once all pods show `Running` status, access the Appwrite Console through the configured ingress or by port-forwarding: + +```bash +kubectl port-forward svc/appwrite 3000:80 +``` + +Navigate to `http://localhost:3000` to complete the initial setup wizard. + +{% /section %} + +# Configuration {% #configuration %} + +Create a `values.yaml` file to customize the deployment: + +```yaml +domain: appwrite.example.com + +ingress: + enabled: true + ingressClassName: nginx + +smtp: + host: smtp.example.com + port: 587 + username: user@example.com + password: your-password +``` + +Install with your custom values: + +```bash +helm install appwrite helmforge/appwrite -f values.yaml +``` + +# Architecture {% #architecture %} + +The chart deploys Appwrite as multiple Kubernetes resources: + +- **API, Console, Realtime** — separate Deployments with path-based ingress routing +- **12 background workers** and **3 schedulers** — configurable resource limits +- **MariaDB and Redis** — bundled as subcharts, or connect to external instances +- **Persistent volumes** — for uploads, cache, certificates, functions, builds, and sites + +# External databases {% #external-databases %} + +To use external MariaDB and Redis instances instead of the bundled subcharts: + +```yaml +mariadb: + enabled: false + +redis: + enabled: false + +externalMariadb: + host: your-mariadb-host + port: 3306 + database: appwrite + username: appwrite + password: your-password + +externalRedis: + host: your-redis-host + port: 6379 +``` + +# Next steps {% #next-steps %} + +After successful deployment: + +- [Configure services](/docs/advanced/self-hosting/configuration) - Set up email, storage, and other services +- [Production optimization](/docs/advanced/self-hosting/production) - Prepare for production workloads +- [Chart documentation](https://helmforge.dev/docs/charts/appwrite) - Full values reference and architecture details From 93ac55441b37a04d5b04fce569df085244d78cfd Mon Sep 17 00:00:00 2001 From: Maicon Berlofa Date: Wed, 1 Apr 2026 13:04:35 -0300 Subject: [PATCH 2/3] doc: fix OCI install flow, service name, and add secrets guidance --- .../platforms/kubernetes/+page.markdoc | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc b/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc index 97ea7e3a54..a8d0653386 100644 --- a/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc +++ b/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc @@ -27,20 +27,22 @@ helm repo add helmforge https://repo.helmforge.dev helm repo update ``` -Alternatively, install directly from the OCI registry: - -```bash -helm install appwrite oci://ghcr.io/helmforgedev/helm/appwrite -``` - {% /section %} {% section #install-chart step=2 title="Install Appwrite" %} +Using the Helm repository: + ```bash helm install appwrite helmforge/appwrite ``` +Or directly from the OCI registry (skips step 1): + +```bash +helm install appwrite oci://ghcr.io/helmforgedev/helm/appwrite +``` + This installs Appwrite with bundled MariaDB and Redis subcharts. All core services are deployed as separate pods, including the API, Console, Realtime, background workers, and schedulers. {% /section %} @@ -56,7 +58,7 @@ kubectl get pods -l app.kubernetes.io/instance=appwrite Once all pods show `Running` status, access the Appwrite Console through the configured ingress or by port-forwarding: ```bash -kubectl port-forward svc/appwrite 3000:80 +kubectl port-forward svc/appwrite-appwrite-console 3000:80 ``` Navigate to `http://localhost:3000` to complete the initial setup wizard. @@ -73,12 +75,6 @@ domain: appwrite.example.com ingress: enabled: true ingressClassName: nginx - -smtp: - host: smtp.example.com - port: 587 - username: user@example.com - password: your-password ``` Install with your custom values: @@ -87,6 +83,10 @@ Install with your custom values: helm install appwrite helmforge/appwrite -f values.yaml ``` +{% info title="Secrets management" %} +Avoid storing sensitive values like SMTP passwords directly in `values.yaml`. Instead, use `helm install --set` sourced from your CI/CD secret store, or use a Kubernetes secrets management tool. +{% /info %} + # Architecture {% #architecture %} The chart deploys Appwrite as multiple Kubernetes resources: From 98581caee9268a0cdbe1c57d18ce3a7a4eb85fca Mon Sep 17 00:00:00 2001 From: Maicon Berlofa Date: Wed, 1 Apr 2026 13:12:17 -0300 Subject: [PATCH 3/3] doc: use upgrade --install and fix configuration link --- .../advanced/self-hosting/platforms/kubernetes/+page.markdoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc b/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc index a8d0653386..2a60f8c1ac 100644 --- a/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc +++ b/src/routes/docs/advanced/self-hosting/platforms/kubernetes/+page.markdoc @@ -80,7 +80,7 @@ ingress: Install with your custom values: ```bash -helm install appwrite helmforge/appwrite -f values.yaml +helm upgrade --install appwrite helmforge/appwrite -f values.yaml ``` {% info title="Secrets management" %} @@ -123,6 +123,6 @@ externalRedis: After successful deployment: -- [Configure services](/docs/advanced/self-hosting/configuration) - Set up email, storage, and other services +- [Configure services](/docs/advanced/self-hosting/configuration/environment-variables) - Set up environment variables and services - [Production optimization](/docs/advanced/self-hosting/production) - Prepare for production workloads - [Chart documentation](https://helmforge.dev/docs/charts/appwrite) - Full values reference and architecture details