Dify

Overview

Dify is an open-source builder for LLM applications: chatbots, agents and visual workflows with RAG knowledge bases. You build an app in the browser, then publish it as a web page, call it through the REST service API or expose it as an MCP server. This template runs Dify on a bundled PostgreSQL with pgvector and a bundled Redis. A login is always required.

This template does not create a GVC. It deploys into an existing GVC that you already have, and that GVC should have exactly one location, because the database, Redis, both volumes and the plugin daemon run in one location.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-dify`	nginx gateway on port `8080`, the only public workload (standard, 1 replica by default, up to 3)	—
Workload	`RELEASE_NAME-dify-web`	Console and published web apps on port `3000`	—
Workload	`RELEASE_NAME-dify-api`	Console API, service API and MCP server on port `5001`; applies database migrations at start	—
Workload	`RELEASE_NAME-dify-worker`	Celery worker for document indexing and asynchronous tasks (1 replica by default, up to 3)	—
Workload	`RELEASE_NAME-dify-beat`	Scheduler for periodic tasks (always 1 replica)	—
Workload	`RELEASE_NAME-dify-plugin-daemon`	Installs and runs model-provider and tool plugins (stateful, 1 replica)	—
Workload	`RELEASE_NAME-dify-sandbox`	Runs the Python and JavaScript of Code and Template nodes	Omitted when `codeExecution.endpoint` is set
Workload	`RELEASE_NAME-dify-ssrf-proxy`	squid proxy on port `3128` that keeps flows’ HTTP requests off private and in-GVC addresses	`ssrfProxy.enabled: true` (default)
Volume set	`RELEASE_NAME-dify-storage`	Shared file storage mounted by the API and worker (uploads and the keys that decrypt saved provider credentials)	—
Volume set	`RELEASE_NAME-dify-plugins`	Installed plugins and their Python environments	—
Identity	`RELEASE_NAME-dify-identity`	Workload identity for the Dify tiers	—
Policy	`RELEASE_NAME-dify-policy`	Grants the identity `reveal` on exactly the secrets you name	—
Identity	`RELEASE_NAME-dify-sandbox-identity`	Workload identity for the code sandbox	—
Policy	`RELEASE_NAME-dify-sandbox-policy`	Grants the sandbox `reveal` on its own key only	—
Workload	`RELEASE_NAME-postgres`	PostgreSQL with pgvector (stateful, 1 replica)	`postgres.enabled: true` (default)
Volume set	`RELEASE_NAME-pg-vs`	PostgreSQL data volume	`postgres.enabled: true` (default)
Identity	`RELEASE_NAME-pg-identity`	Workload identity for PostgreSQL	`postgres.enabled: true` (default)
Policy	`RELEASE_NAME-pg-policy`	Grants the PostgreSQL identity `reveal` on the database credentials secret	`postgres.enabled: true` (default)
Workload	`RELEASE_NAME-postgres-backup`	Scheduled backups of PostgreSQL to object storage	`postgres.backup.enabled: true`
Workload	`RELEASE_NAME-postgres-ha`	Patroni PostgreSQL (stateful, 3 replicas by default)	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-etcd`	etcd cluster for Patroni	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-proxy`	HAProxy endpoint that always points at the PostgreSQL leader	`postgresHA.enabled: true`
Volume set	`RELEASE_NAME-postgres-ha-vs`	PostgreSQL data volume, one per replica	`postgresHA.enabled: true`
Volume set	`RELEASE_NAME-etcd-vs`	etcd data volume	`postgresHA.enabled: true`
Identity	`RELEASE_NAME-postgres-ha-identity`	Workload identity for Patroni PostgreSQL	`postgresHA.enabled: true`
Policy	`RELEASE_NAME-postgres-ha-policy`	Grants the Patroni identity `reveal` on its startup secrets and the database credentials secret	`postgresHA.enabled: true`
Identity	`RELEASE_NAME-etcd-identity`	Workload identity for etcd	`postgresHA.enabled: true`
Policy	`RELEASE_NAME-etcd-policy`	Grants the etcd identity `reveal` on its startup secret	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-patroni-startup`	Patroni startup script	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-etcd-startup`	etcd startup script	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-postgres-proxy-startup`	HAProxy startup script	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-wal-g-backup-script`	Backup script used when backups are enabled	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-backup`	Scheduled backups of the Patroni PostgreSQL	`postgresHA.backup.enabled: true`
Secret	`RELEASE_NAME-postgres-config`	Backup configuration	`postgresHA.backup.enabled: true`
Workload	`RELEASE_NAME-redis`	Cache, task queue and plugin state (single node, password required)	`redis.enabled: true` (default)
Identity	`RELEASE_NAME-redis-identity`	Workload identity for Redis	`redis.enabled: true` (default)
Policy	`RELEASE_NAME-redis-policy`	Grants the Redis identity access to its configuration secret	`redis.enabled: true` (default)
Secret	`RELEASE_NAME-redis-config`	Redis configuration	`redis.enabled: true` (default)

The template creates no credentials. The public *.cpln.app URL is on by default and every page needs a Dify login. Each Dify tier accepts connections only from the tiers that call it.

Prerequisites

Create the Dify keys secret

A dictionary secret holding Dify’s own keys. Use only letters and digits in every value, and keep initPassword to at most 30 characters:

cpln secret create-dictionary --name DIFY_SECRET_NAME \
  --entry secretKey="$(openssl rand -hex 32)" \
  --entry initPassword="$(openssl rand -hex 12)" \
  --entry pluginDaemonKey="$(openssl rand -hex 32)" \
  --entry pluginInnerApiKey="$(openssl rand -hex 32)"

Set dify.secretName to this name.

Create the code sandbox key secret

An opaque secret holding the key that Dify and the code sandbox share:

printf '%s' "$(openssl rand -hex 32)" | \
  cpln secret create-opaque --name SANDBOX_KEY_SECRET_NAME --encoding plain -f -

Set codeExecution.apiKeySecretName to this name.

Create the database credentials secret

A dictionary secret with exactly username, password and database, letters and digits only:

cpln secret create-dictionary --name DB_CREDENTIALS_SECRET_NAME \
  --entry username=dify \
  --entry password="$(openssl rand -hex 32)" \
  --entry database=dify

Set postgres.config.credentialsSecretName to this name (or postgresHA.config.credentialsSecretName with the HA database).

Create the Redis password secret

A dictionary secret with a password key, letters and digits only. A password is required because user code runs inside this GVC:

cpln secret create-dictionary --name REDIS_SECRET_NAME \
  --entry password="$(openssl rand -hex 32)"

Set redis.redis.auth.fromSecret.name to this name.

Secret names are org-wide, so give each release its own secrets. A value with other characters stops the API, worker and scheduler at start with a log line naming the key. Backups and a custom domain are optional, see Backing Up and Connecting.

Every secret your release names must exist before you install. If one does not, the deployment waits silently: cpln logs returns nothing, and the only place the missing secret is named is status.versions[].message in cpln workload get-deployments RELEASE_NAME-dify-api --gvc GVC_NAME -o yaml. Create the secret and the deployment recovers on its own after several minutes, or run cpln workload force-redeployment WORKLOAD_NAME --gvc GVC_NAME on each Dify workload to skip the wait.

Installation

The required values are the names of the four secrets from Prerequisites:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/dify \
  --version 1.0.0 --gvc GVC_NAME \
  --set dify.secretName=DIFY_SECRET_NAME \
  --set codeExecution.apiKeySecretName=SANDBOX_KEY_SECRET_NAME \
  --set postgres.config.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME \
  --set redis.redis.auth.fromSecret.name=REDIS_SECRET_NAME

To install with the highly available database, add

--set postgres.enabled=false --set postgresHA.enabled=true --set postgresHA.config.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME

. To install with the CLI, UI, Terraform or Pulumi, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

dify:
  # Official images; api, worker and beat share apiImage. Keep api and web on the same tag.
  apiImage: langgenius/dify-api:1.19.0
  webImage: langgenius/dify-web:1.19.0
  gatewayImage: nginx:1.30.6-alpine
  # Replicas of the gateway, web, API, code sandbox and SSRF proxy (1-3).
  # set dify.replicas: 2, worker.replicas: 2 and postgresHA.enabled: true for near-zero-downtime upgrades and failover
  replicas: 1
  secretName: my-dify-secrets
  publicUrl: ""                 # "" = the gateway's *.cpln.app endpoint; or https://dify.example.com (no trailing /) for a custom domain
  requestTimeoutSeconds: 600    # longest request or stream on the public URL before it is cut (1-3600)
  volumeset:
    capacity: 10                # GiB (minimum 10): uploads and the keys that decrypt stored provider credentials; never delete it
  # Plain (non-secret) Dify settings for api, worker and beat, e.g. UPLOAD_FILE_SIZE_LIMIT, LOG_LEVEL.
  extraEnv: []
  # extraEnv:
  #   - name: UPLOAD_FILE_SIZE_LIMIT
  #     value: "50"
  resources:
    api:
      minCpu: 250m
      maxCpu: 1000m
      minMemory: 512Mi
      maxMemory: 1536Mi

The gateway, web and beat tiers take the same resources shape under dify.resources.

worker:
  replicas: 1                   # 1-3
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1536Mi
pluginDaemon:
  image: langgenius/dify-plugin-daemon:0.6.14-local
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi
  volumeset:
    capacity: 20                # GiB (minimum 10): installed plugins and their Python environments

Each API and worker process holds up to 8 database connections (SQLALCHEMY_POOL_SIZE 5 plus SQLALCHEMY_MAX_OVERFLOW 3), which allows about 8 concurrent runs per API replica. To allow more, set both in dify.extraEnv, staying within PostgreSQL’s 100 connections:

dify:
  extraEnv:
    - name: SQLALCHEMY_POOL_SIZE
      value: "20"
    - name: SQLALCHEMY_MAX_OVERFLOW
      value: "10"

Code Execution and Network

codeExecution:
  endpoint: ""                  # "" = the bundled dify-sandbox workload; or the URL of your own sandbox-compatible executor
  apiKeySecretName: my-dify-sandbox-key
  sandbox:
    image: langgenius/dify-sandbox:0.2.15
    resources:
      minCpu: 100m
      maxCpu: 500m
      minMemory: 128Mi
      maxMemory: 512Mi
ssrfProxy:
  enabled: true                 # false lets HTTP Request nodes, tools and code call any service in this GVC
  image: ubuntu/squid:6.6-24.04_edge
publicAccess:
  enabled: true                 # public *.cpln.app URL; /install is guarded by initPassword, every page needs a login
internalAccess:                 # who in Control Plane may reach the gateway (the other tiers admit only each other)
  type: same-gvc                # none | same-gvc | same-org | workload-list
  workloads: []                 # used only with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

Database

postgres:                       # every knob of the postgres template
  enabled: true
  image: pgvector/pgvector:0.8.7-pg18
  config:
    credentialsSecretName: my-dify-db-credentials
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1Gi
  volumeset:
    capacity: 10                # GiB (minimum 10)
  backup:
    enabled: false              # scheduled backups to object storage; provider aws, gcp or minio (postgres template)
postgresHA:                     # every knob of the postgres-highly-available template
  enabled: false                # enable exactly one of postgres / postgresHA
  image: controlplanecorporation/patroni-postgres:0.8   # includes pgvector 0.8.7
  config:
    credentialsSecretName: my-dify-db-credentials
  replicas: 3
  resources:                    # per Patroni replica
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi
  volumeset:
    capacity: 10                # GiB per replica (minimum 10)
  backup:
    enabled: false              # logical or wal-g backups (postgres-highly-available template)

Redis

redis:
  enabled: true                 # required
  mode: dev                     # required: one node; the chart refuses production (Sentinel) mode
  redis:
    image: redis:8
    resources:
      maxCpu: 200m
      maxMemory: 256Mi
      minCpu: 80m
      minMemory: 128Mi
    auth:
      fromSecret:
        enabled: true
        name: my-dify-redis
        passwordKey: password

Connecting

What	Address	Notes
Console (public)	`status.canonicalEndpoint` of `cpln workload get RELEASE_NAME-dify --gvc GVC_NAME -o yaml`	See First Run
From your machine (private install)	`cpln port-forward RELEASE_NAME-dify 8080:8080 --gvc GVC_NAME`, then `http://localhost:8080`	Requires `dify.publicUrl: http://localhost:8080`
Service API	`POST PUBLIC_URL/v1/chat-messages` or `/v1/workflows/run`	Header `Authorization: Bearer APP_API_KEY`; create the key on the app’s API Access page
Internal service API	`http://RELEASE_NAME-dify.GVC_NAME.cpln.local:8080/v1`	Reachable per `internalAccess`
App as MCP server	`PUBLIC_URL/mcp/server/.../mcp`	Turn on MCP Server for an app; the app shows the full URL
Webhook trigger	`PUBLIC_URL/triggers/webhook/...`	A published workflow with a webhook trigger node shows its URL
Control Plane MCP server	Tools → MCP → add `https://mcp.cpln.io/mcp?toolsets=readonly`	Sign in with your Control Plane account through OAuth; the read-only toolset has no create, update or delete tools
Models	Settings → Model Provider	Install a model-provider plugin, then enter its API key there

Dify builds every link, cookie and webhook from the public URL, and the login works only on that exact address. With dify.publicUrl empty it is the gateway’s *.cpln.app endpoint. Behind a custom domain, route the domain to the RELEASE_NAME-dify workload and set dify.publicUrl to it. With publicAccess.enabled: false, set dify.publicUrl to the address users open, such as http://localhost:8080 for port-forward. To check the gateway, forward the port and read its health:

cpln port-forward RELEASE_NAME-dify 8080:8080 --gvc GVC_NAME
curl http://localhost:8080/gateway-health

Streaming responses and long runs pass through the gateway unbuffered. The public endpoint cuts a request after dify.requestTimeoutSeconds; calls from inside the GVC over cpln.local are not subject to it.

First Run

Open the public URL. Dify asks for the initPassword from the Dify keys secret, then lets you create the admin account on the /install page. Read the password with cpln secret reveal DIFY_SECRET_NAME -o yaml. Self sign-up and creating more workspaces are turned off; invite members from Settings → Members, which shows an invite link to copy because the template sends no email.

Operations

Backing Up

All state lives in PostgreSQL and the file storage volume. Enable postgres.backup.enabled (or postgresHA.backup.enabled with the HA database) and fill in the provider block; the keys and defaults are in the chart’s values.yaml. The bucket, cloud account and IAM policy are set up as described in the postgres or postgres-highly-available template, and a MinIO provider needs a dictionary secret with the keys accessKey and secretKey. Restore steps are in those templates’ pages. The backup covers the database only; uploaded files and the keys that decrypt saved provider credentials on the file storage volume are not included.

Scaling and Availability

Set dify.replicas from 1 to 3 for the gateway, web, API, code sandbox and SSRF proxy, and worker.replicas from 1 to 3 for the worker. The scheduler and the plugin daemon always run one replica. When several API replicas start together, one applies the database migrations and the others wait for it. For near-zero-downtime upgrades and failover, set dify.replicas: 2, worker.replicas: 2 and postgresHA.enabled: true. Redis stays a single node. After changing a secret a workload reads, redeploy the workloads that use it:

cpln workload force-redeployment WORKLOAD_NAME --gvc GVC_NAME

Dify locks an email address out for 24 hours after 6 failed logins, from any address. To clear it, delete the lock from Redis:

cpln workload exec RELEASE_NAME-redis --gvc GVC_NAME --container redis -- sh -c 'REDISCLI_AUTH="$CUSTOM_REDIS_PASSWORD" redis-cli DEL login_error_rate_limit:USER_EMAIL'

Troubleshooting

The deployment is stuck and cpln logs returns nothing

A secret named in the values does not exist. Read status.versions[].message with cpln workload get-deployments RELEASE_NAME-dify-api --gvc GVC_NAME -o yaml, create the secret, then run cpln workload force-redeployment WORKLOAD_NAME --gvc GVC_NAME on each Dify workload.

The API, worker or scheduler stops at start with a log line naming a key

A database or Redis value contains characters other than letters and digits, secretKey is empty, or initPassword is longer than 30 characters. Fix the secret and redeploy the Dify workloads.

An HTTP Request node cannot reach a service in my GVC

The SSRF proxy refuses private, link-local and in-GVC addresses (*.cpln.local) for HTTP Request nodes, tools and Python HTTP calls. Set ssrfProxy.enabled: false to lift it, knowing that flows can then call any service in the GVC. Model-provider plugins run in the plugin daemon, not through the proxy, so Ollama, vLLM and LiteLLM providers can use in-GVC URLs.

Runs fail with QueuePool limit of size 5 overflow 3 reached

Concurrent runs exhausted the database connection pool. Raise SQLALCHEMY_POOL_SIZE and SQLALCHEMY_MAX_OVERFLOW in dify.extraEnv, as shown in Configuration.

Long runs are cut off on the public URL

The public endpoint cuts requests after dify.requestTimeoutSeconds (default 600, maximum 3600). Raise it for longer calls.

An email is locked out after failed logins

Clear the lock as shown in Clearing a Login Lockout.

The chart refuses to render

The error names the offending value. The template rejects replica counts outside 1-3, enabling both or neither database, redis.mode other than dev, and extraEnv names that the chart sets itself.

Important Notes

The Dify licence allows one workspace per install, not a multi-tenant service, and forbids removing or changing the Dify logo and copyright in the console.
Never rotate secretKey (it signs every login and shared link) and never delete the file storage volume (it holds the keys that decrypt the model-provider credentials saved in Dify).
Anyone who can edit an app can run Python and JavaScript in the code sandbox, and that code can open direct connections to the internet. The Dify API, web and plugin daemon refuse the sandbox, but the other services in this GVC, including the bundled PostgreSQL and Redis, are guarded only by their passwords. Give accounts only to people you trust.
With the SSRF proxy on, HTTP Request nodes, tools and Python requests calls in Code nodes go through it. JavaScript code gets no proxy.
Plugins install from the Dify marketplace or an uploaded package, and only signed plugins are accepted.
Use a single-location GVC: the database, Redis, both volumes and the plugin daemon run in one location.
The first helm upgrade after an install can restart the bundled database, which briefly interrupts Dify.
Uninstalling deletes the database and both volumes, and with them every app, user, knowledge base and installed plugin.

External References

Dify documentation

Concepts, apps and deployment

Environment variables

Dify settings

Dify service API

Calling published apps over REST

Dify as an MCP server

Exposing apps as MCP tools

Dify on GitHub

Source, licence and issues

Template Catalog

Templates

Dify

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Dify

Code Execution and Network

Database

Redis

Connecting

First Run

Operations

Backing Up

Scaling and Availability

Troubleshooting

Important Notes

External References

Dify documentation

Environment variables

Dify service API

Dify as an MCP server

Dify on GitHub

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Dify

​Code Execution and Network

​Database

​Redis

​Connecting

​First Run

​Operations

​Backing Up

​Scaling and Availability

​Clearing a Login Lockout

​Troubleshooting

​Important Notes

​External References

Dify documentation

Environment variables

Dify service API

Dify as an MCP server

Dify on GitHub

Overview

What Gets Created

Prerequisites

Installation

Configuration

Dify

Code Execution and Network

Database

Redis

Connecting

First Run

Operations

Backing Up

Scaling and Availability

Clearing a Login Lockout

Troubleshooting

Important Notes

External References