Helm: Configuring settings

The Helm chart passes Zulip’s configuration to the container through environment variables defined under zulip.environment in your values file. These use the same SETTING_*, CONFIG_*, and SECRET_* prefixes as the Docker Compose deployment; see Docker Zulip environment variables for the full reference.

Required settings

The following settings are always required:

  • SETTING_EXTERNAL_HOST: The hostname your users will use to connect to your Zulip server.

  • SETTING_ZULIP_ADMINISTRATOR: The email address to receive error and support emails generated by the Zulip server and its users.

  • SECRETS_secret_key: The secret key used by Django for cryptographic signing.

Providing settings in a values file

  1. Create a values-local.yaml file with your settings under zulip.environment:

    zulip:
  environment:
    SETTING_EXTERNAL_HOST: zulip.example.com
    SETTING_ZULIP_ADMINISTRATOR: "admin@example.com"
    SECRETS_secret_key: "replace-with-a-secure-secret-key"
    SETTING_EMAIL_HOST: "smtp.example.com"
    SETTING_EMAIL_HOST_USER: "noreply@example.com"
    SETTING_EMAIL_PORT: "587"
    SETTING_EMAIL_USE_TLS: "True"

  2. Install or upgrade with your values file:

    helm install zulip oci://ghcr.io/zulip/helm-charts/zulip -f values-local.yaml
# or, to update an existing release:
helm upgrade zulip oci://ghcr.io/zulip/helm-charts/zulip -f values-local.yaml

Referencing Kubernetes Secrets with valueFrom

Instead of placing sensitive values directly in your values file, you can reference Kubernetes Secrets using valueFrom. This is the recommended approach for production deployments.

  1. Create a Kubernetes Secret with your sensitive values:

    kubectl create secret generic zulip-secrets \
    --from-literal=secret-key='your-secret-key'

  2. Reference the secret in your values file:

    zulip:
  environment:
    SECRETS_secret_key:
      valueFrom:
        secretKeyRef:
          name: zulip-secrets
          key: secret-key

Post-setup scripts

The Docker entrypoint runs scripts from /data/post-setup.d/ after the application’s setup phase completes (controlled by ZULIP_RUN_POST_SETUP_SCRIPTS). You can add scripts using postSetup.scripts in your values file:

postSetup:
  scripts:
    custom-branding.sh: |
      #!/bin/bash
      echo "Running post-setup customization..."

These scripts are mounted into the container via a ConfigMap and execute on every container startup after the setup phase.

See also