DOCSEARCHbyAlgolia
Submit Docs

dify-helm

repository·master·Indexed 20 days ago

https://github.com/borispolonsky/dify-helm

A Helm chart for deploying Dify, an LLM-based chatbot application, onto Kubernetes clusters (v1.23+). It manages a microservices architecture including API servers, web frontends, background workers, and specialized services for sandboxed code execution and plugin management. The chart supports built-in middlewares (Redis, PostgreSQL, Weaviate) or integration with external managed services for databases, object storage, and vector databases. It also provides support for External Secrets Operator for sensitive configuration.

Tokens
3.4K
Snippets
9
Records
13
Agent score
21%

What's inside dify-helm

  1. Understand the Dify Network Architecture and Traffic Routing

    master

    The deployment uses an Nginx proxy to route incoming traffic to various backend services based on the URL path.

    Routing Rules:

    • /console/api, /api, /v1, /files, /mcp, /triggers $\rightarrow$ API Service (Port 5001)
    • /e/ $\rightarrow$ Plugin Daemon (Port 5002)
    • /explore $\rightarrow$ Web Service (Port 3000)
    • /marketplace $\rightarrow$ External Marketplace API
    • / (Default) $\rightarrow$ Web Service (Port 3000)

    Traffic Flow: External traffic enters via an Ingress Controller or LoadBalancer, hits the Nginx Proxy Pod (Port 80), which then distributes requests to the API, Web, or Plugin services.

  2. Configure built-in middlewares (Redis, PostgreSQL, Weaviate)

    master

    The chart includes built-in middlewares for a self-contained environment. These are provided by third-party Helm charts and are enabled by default. To customize them, refer to their respective documentation:

    SectionDocumentationEnabled by Default
    redisbitnami/redistrue
    postgresqlbitnami/postgresqltrue
    weaviateweaviatetrue

    Note: Built-in versions may differ from Dify's docker-compose.yml versions.

  3. Use external components with Dify

    master

    The Helm chart supports offloading data and storage layers to external managed services or standalone instances. This is useful for production environments where persistence and scalability are critical.

    Supported External Services:

    • Redis: Standalone or Sentinel.
    • Databases: PostgreSQL and MySQL.
    • Object Storage: Amazon S3, Microsoft Azure Blob Storage, Alibaba Cloud OSS, Google Cloud Storage, Tencent Cloud COS, Huawei Cloud OBS, and Volcengine TOS.
    • Vector Databases: Weaviate, Qdrant, Milvus, PGVector, Tencent Vector DB, MyScaleDB, TableStore, and Elasticsearch.

  4. Use ExternalSecret for sensitive configuration

    master

    For production environments, instead of storing plain-text passwords in values.yaml, you can use the External Secrets Operator to retrieve sensitive data from providers like AWS Secrets Manager, HashiCorp Vault, or Azure Key Vault.

    To enable this, set externalSecret.enabled: true in your values.yaml and configure the secretStore and remoteRefs parameters.

    Supported components for ExternalSecret integration:

    • Databases: PostgreSQL (username, password), Redis (username, password), Elasticsearch (username, password).
    • Object Storage: AWS S3 (Access Key ID, Secret Access Key).
    • Vector Databases: Elasticsearch (username, password).
    • Email Services: Resend (API Key, sender email), SendGrid (API Key, sender email).
    • Core Services: Code Execution Service (API Key), Plugin System (Daemon Key, internal API Key), Application Core (Secret Key).

  5. Migrate built-in Redis and PostgreSQL to separate releases

    master

    If you need to move from the built-in Redis and PostgreSQL instances provided by the dify-helm chart to standalone Bitnami releases while preserving data, follow these steps:

    1. Prerequisites: Ensure you are using the default replication architecture. Add the Bitnami repository:
      helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
    2. Backup: Back up your current Helm values, ConfigMaps, and Secrets. This is critical because randomly generated passwords in the built-in setup will not persist after migration.
    3. Prepare New Database Configs: Create redis-values.yaml and postgresql-values.yaml. You must use persistence.existingClaim or fullnameOverride to point the new Bitnami releases to your existing PVCs.
    4. Disable Built-in Databases: Upgrade your Dify release with redis.enabled=false and postgresql=false in your values file. Wait for the pods to terminate.
    5. Deploy Standalone Databases: Install the Bitnami Redis and PostgreSQL charts using the configuration files created in step 3.
    6. Update Dify to use External DBs: Upgrade the Dify release again, setting redis.enabled: false, postgresql.enabled: false, and enabling externalRedis and externalPostgres with the correct host, port, and credentials.
    # Example redis-values.yaml to reuse existing PVC
master:
  count: 1
  persistence:
    existingClaim: "redis-data-my-release-redis-master-0"
replica:
  replicaCount: 3
  persistence:
    existingClaim: ""

# Example postgresql-values.yaml to reuse existing PVC
primary:
  persistence:
    existingClaim: "data-my-release-postgresql-primary-0"
readReplicas:
  replicaCount: 1
  persistence:
    existingClaim: "data-my-release-postgresql-read-0"

  6. Install dify-helm via Helm

    master

    To deploy the Dify LLM-based chatbot application on Kubernetes, use the following steps to add the repository and install the chart.

    Prerequisites:

    • Kubernetes: version 1.23 or higher
    • Helm: version 3.12 or higher

    For advanced or customized installations, refer to the specific chart documentation located at charts/dify/README.md within the repository.

    helm repo add dify https://borispolonsky.github.io/dify-helm
helm repo update
helm install my-release dify/dify

  7. Use external services instead of built-in middlewares

    master

    For production environments, it is recommended to use external providers for Redis, PostgreSQL, and Weaviate to improve maintainability and allow independent upgrade cycles.

    To switch to an external service, you must:

    1. Disable the built-in middleware (e.g., redis.enabled: false).
    2. Enable the corresponding external<Service> section (e.g., externalRedis.enabled: true) and provide the connection details.

    Example for external Redis:

    # values.yaml
redis:
  enabled: false  # Disable built-in Redis

externalRedis:
  enabled: true
  host: "redis.example"
  port: 6379
  username: ""
  password: "difyai123456"
  useSSL: false

  9. Migrate built-in Weaviate to a separate release

    master

    To migrate from the built-in Weaviate instance to a standalone Weaviate Helm release:

    1. Prerequisites: Add the Weaviate repository:
      helm repo add weaviate https://weaviate.github.io/weaviate-helm
helm repo update
    2. Backup: Back up your Dify Helm values and Kubernetes Secrets/ConfigMaps.
    3. Disable Built-in Weaviate: Upgrade your Dify release with weaviate.enabled=false. Wait for the pods to terminate.
    4. Deploy Standalone Weaviate: Extract your current .Values.weaviate section, un-nest it so it is just .Values, and use it as the configuration for the new weaviate/weaviate Helm installation.
    5. Update Dify Configuration: Upgrade Dify to use the external service by setting weaviate.enabled: false and configuring externalWeaviate with the correct endpoint.http and endpoint.grpc URLs and the apiKey.
    # Example dify-external-weaviate-values.yaml
weaviate:
  enabled: false

externalWeaviate:
  enabled: true
  endpoint:
    http: "http://weaviate:80"
    grpc: "grpc://weaviate:50051"
  apiKey: "your-api-key"

  10. Add extra environment variables to Dify components

    master

    Use the extraEnv section within a component's configuration to add new environment variables or override existing ones. You can use direct value assignment or reference existing configMapKeyRef or secretKeyRef objects.

    # values.yaml
api:
  extraEnv:
  # Direct value assignment
  - name: LANG
    value: "C.UTF-8"
  # Use existing configmaps
  - name: MY_CONFIG
    valueFrom:
      configMapKeyRef:
        name: my-config
        key: MY_CONFIG
  # Use existing secrets
  - name: MY_SECRET
    valueFrom:
      secretKeyRef:
        name: my-secret
        key: MY_SECRET

  11. Use alternative images for Dify components

    master

    You can override the default container images for all Dify components by configuring the image section in your values.yaml. This is useful when using a private registry or specific image tags.

    Supported components include:

    • api
    • web
    • sandbox
    • proxy
    • ssrfProxy
    • pluginDaemon
    # values.yaml
image:
  api:
    repository: your-registry/dify-api
    tag: "your-tag"
    pullPolicy: IfNotPresent
  web:
    repository: your-registry/dify-web
    tag: "your-tag"
    pullPolicy: IfNotPresent
  sandbox:
    repository: your-registry/dify-sandbox
    tag: "your-tag"
    pullPolicy: IfNotPresent
  proxy:
    repository: your-registry/nginx
    tag: "your-tag"
    pullPolicy: IfNotPresent
  ssrfProxy:
    repository: your-registry/squid
    tag: "your-tag"
    pullPolicy: IfNotPresent
  pluginDaemon:
    repository: your-registry/dify-plugin-daemon
    tag: "your-tag"
    pullPolicy: IfNotPresent

  12. Configure data persistence for Dify components

    master

    To enable and customize data persistence for a component (e.g., api), set enabled: true in the component's persistence section. You can either specify a storageClass and size or designate an existing PersistentVolumeClaim via existingClaim.

    # Option 1: Using storageClass and size
api:
  persistence:
    enabled: true
    storageClass: your-storage-class
    accessMode: ReadWriteMany
    size: 10Gi

# Option 2: Using an existing PVC
api:
  persistence:
    enabled: true
    persistentVolumeClaim:
      existingClaim: "your-pvc-name"