Appwrite

Deploy Appwrite on Kubernetes — a self-hosted Backend-as-a-Service (BaaS) platform providing authentication, databases, storage, functions, messaging, and a real-time API. Ships as a multi-workload chart (~20 Kubernetes Deployments) with bundled MariaDB and Redis.

Key Features

• Full Appwrite stack — API, Console IV 1.1.159-self-hosted, Realtime WebSocket, 15 workers, schedulers, maintenance
• ~20 Kubernetes workloads — each component runs independently and scales separately
• MariaDB + Redis — bundled subcharts or external connections
• Shared PVCs — uploads, cache, certificates, functions, builds, and sites shared across pods
• Root DB access required — Appwrite needs MariaDB root credentials for schema migrations
• Ingress routing — Console at /, API at /v1, Realtime WebSocket at /v1/realtime
• Side-effect-free health probes — API health uses the public /v1/health/version endpoint
• mysqldump backup — scheduled CronJob to S3

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install appwrite helmforge/appwrite -f values.yaml

OCI registry:

helm install appwrite oci://ghcr.io/helmforgedev/helm/appwrite -f values.yaml

Deployment Examples

# values.yaml — Appwrite with bundled MariaDB and Redis
appwrite:
  domain: appwrite.example.com
  # Generate: openssl rand -hex 32
  openSslKeyV1: 'your-64-char-hex-key-here'

mariadb:
  enabled: true
  auth:
    password: 'strong-db-password'
    rootPassword: 'strong-root-password'
  standalone:
    persistence:
      enabled: true
      size: 20Gi

redis:
  enabled: true
  auth:
    enabled: true
    password: 'strong-redis-password'

persistence:
  enabled: true
  uploads:
    size: 20Gi
  functions:
    size: 10Gi
  builds:
    size: 10Gi

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: appwrite.example.com
      paths:
        - path: /
          pathType: Prefix

# values.yaml — Appwrite with external MariaDB and Redis
# IMPORTANT: External MariaDB needs root credentials for Appwrite schema migrations
appwrite:
  domain: appwrite.example.com
  existingSecret: appwrite-master-secrets # contains openssl key + JWT secret
  existingSecretOpenSslKey: appwrite-openssl-key
  existingSecretJwtKey: appwrite-jwt-secret

mariadb:
  enabled: false

database:
  mode: external
  external:
    host: mariadb.database.svc.cluster.local
    port: 3306
    name: appwrite
    rootUser: root
    existingSecret: appwrite-mariadb-root # needs ROOT password for migrations
    existingSecretPasswordKey: mariadb-root-password

redis:
  enabled: false

cache:
  mode: external
  external:
    host: redis.cache.svc.cluster.local
    port: 6379
    existingSecret: appwrite-redis-credentials
    existingSecretPasswordKey: redis-password

persistence:
  enabled: true
  uploads:
    size: 20Gi

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: appwrite.example.com
      paths:
        - path: /
          pathType: Prefix

# values.yaml — Production Appwrite with SMTP, HTTPS, and backup
appwrite:
  domain: appwrite.example.com
  existingSecret: appwrite-master-secrets
  smtp:
    host: smtp.mailgun.org
    port: '587'
    secure: tls
    username: [email protected]
    existingSecret: appwrite-smtp-credentials
    existingSecretPasswordKey: smtp-password

mariadb:
  enabled: true
  auth:
    password: 'strong-db-password'
    rootPassword: 'strong-root-password'
  standalone:
    persistence:
      enabled: true
      size: 50Gi

redis:
  enabled: true
  auth:
    enabled: true
    password: 'strong-redis-password'
  standalone:
    persistence:
      enabled: true
      size: 4Gi

persistence:
  enabled: true
  uploads:
    size: 50Gi
  functions:
    size: 20Gi
  builds:
    size: 20Gi
  sites:
    size: 20Gi

backup:
  enabled: true
  schedule: '0 3 * * *'
  s3:
    endpoint: https://s3.amazonaws.com
    bucket: appwrite-backups
    existingSecret: appwrite-s3-backup-credentials

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: appwrite.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: appwrite-tls
      hosts:
        - appwrite.example.com

Upgrade Notes

Appwrite 2.3.0

The 2.3 release removes development keys, consolidates generated Console links under _APP_CONSOLE_URL, and ships Console 1.1.159-self-hosted. Its migration touches every project’s users and identities collections, removes the devKeys collection and strips obsolete dev-key scopes; run migrate after upgrading. Remove _APP_CONSOLE_URL_SCHEME from retained environment values. When the Console uses a different host from the API, set _APP_CONSOLE_URL to the full Console origin through extraEnv before upgrading.

Function and site executions now require ClickHouse through _APP_CONNECTIONS_DB_EXECUTIONS; they are no longer read from the project MariaDB database. Provision that external backend before enabling execution features. Preserve/export legacy execution history before upgrading: records stored only in the old project database will no longer be listed. This chart does not provision the executor/orchestrator or migrate historical executions. Remove _APP_EXECUTIONS_DUAL_WRITE, _APP_MAINTENANCE_RETENTION_USAGE_HOURLY and _APP_CONNECTIONS_DB_LOGS from retained environment values. Usage retention belongs to the external ClickHouse deployment.

Earlier 2.1.0 changes

The 2.1 release fixes password-protected Redis queue publishers and consumers, including ACL users and reserved characters in passwords. It adds the S3-compatible API at /v1/s3 using project API keys; the existing storage backend and bucket permissions still apply. Automatic crop gravity remains unconfigured unless an external service is provided through _APP_AUTOGRAVITY_HOST. This chart does not deploy that optional service.

Error reporting now supports only sentry:// DSNs through appwrite.logging.sentryDsn. appwrite.logging.format selects pretty or json container logs. The old logging.provider field is retained only for compatible empty/default/sentry values and no longer emits the removed environment variable. Remove _APP_LOGGING_PROVIDER, _APP_LOGGING_CONFIG_REALTIME and experimental logging provider/config variables from custom environment values before upgrading. The bundled Redis chart is 3.0.0, retaining its image, credentials and storage.

The following 2.0 migration requirements also apply when upgrading directly from 1.9.x.

Back up MariaDB, all shared PVCs and the application Secret before upgrading from 1.9.x. Keep traffic paused during the upgrade and migration. This chart retains MariaDB explicitly; the upstream installer’s new PostgreSQL default does not move existing data between engines.

Use helm upgrade <release> <chart-ref> --reset-then-reuse-values (or explicitly set the new image tag), then run kubectl exec -n <namespace> deploy/<api-deployment> -c api -- migrate. Verify the API, worker logs and existing projects before restoring traffic. To roll back to 2.2, stop new queue receives and drain or recover every in-flight reservation before removing the 2.3 workers. Then restore the database, volumes, Secret and matching old images together.

Console IV uses appwrite/new:1.1.159-self-hosted on port 3000 with the API on the same origin; the console Service still exposes port 80. worker-audits was removed upstream: set workers.audits.enabled=false in retained values. Jobs, screenshots, executions and notifications now have separate worker toggles, alongside the remaining workers. Disabled workers do not process their respective queues.

Generated encryption and JWT Secret entries are retained on upgrade. Supplying a new appwrite.openSslKeyV1 overrides the retained key and requires an application key-rotation procedure; it is not an automatic data re-encryption mechanism.

DocumentsDB, VectorsDB and embeddings remain disabled. This chart does not provision the extra engines, embedding server, executor or orchestrator needed for those features and Functions/Sites execution. Provision and configure those dependencies separately before opting in through extraEnv.

The stats-resources task is deployed only when appwrite.usageStats=enabled and tasks.statsResources.enabled=true; upstream exits immediately when usage is disabled. This avoids restarting an intentionally inactive process.

Usage statistics now require ClickHouse. appwrite.usageStats defaults to disabled; to retain or enable usage reporting, provision a private ClickHouse service (the HelmForge ClickHouse chart can provide it) and supply its TLS-enabled HTTP DSN through a Secret:

appwrite:
  usageStats: enabled
  extraEnv:
    - name: _APP_CONNECTIONS_DB_USAGE
      valueFrom:
        secretKeyRef:
          name: appwrite-usage
          key: dsn
    - name: _APP_CONNECTIONS_DB_EXECUTIONS
      valueFrom:
        secretKeyRef:
          name: appwrite-executions
          key: dsn

Use a DSN such as https://<user>:<password>@clickhouse.example.com:8443/appwrite?secure=true. The secure=true query parameter enables TLS in the Appwrite ClickHouse adapter; the scheme alone is insufficient. URL-encode credentials containing reserved characters. Use a DNS hostname matching the server certificate and a certificate chain trusted by the Appwrite container. The client verifies peers and hostnames; for a private CA, install its root into the container trust store before deployment. In 2.2, usage-setup initializes and checks both usage and execution schemas, so configure both connections before running it in the API pod. Verify schema readiness before enabling traffic. Plan retention of historical usage data separately from new usage schema setup. Back up external ClickHouse independently; the chart S3 backup covers the core MariaDB and shared-volume data.

Configuration Reference

Core

Images

Appwrite Configuration

Logging

SMTP

Services

Each service can be scaled independently:

Workers

The 15 supported workers are enabled by default at replicaCount: 1. The table also lists the legacy workers.audits key, which must remain disabled.

Each supported worker accepts enabled, replicaCount, and resources fields.

Database

Persistence

All PVCs are shared across workers and the API. If api.replicaCount > 1, the storage class must support ReadWriteMany.

Backup

Ingress

More Information

• Appwrite Official Documentation
• Appwrite GitHub Repository
• HelmForge Appwrite Chart Source