Docker Deployment and Upgrades#

Overview#

Dify ships a Docker Compose stack in the docker/ directory. The docker-compose.yaml is auto-generated from .env.example and docker-compose-template.yaml and must not be edited directly 1. All customization goes into docker/.env, which overrides the defaults baked into the compose file 2.

Core Services#

The stack defines these primary services 3:

Vector store backends (Weaviate, Qdrant, Milvus, OpenSearch, PGVector, etc.) are optional and activated via COMPOSE_PROFILES 4.

Environment Variable Management#

Configuration Precedence#

Variables are resolved in this order (later source wins) 2 5:

1. docker/envs/**/*.env files (optional per-service overrides; copy the matching *.env.example without the .example suffix to enable)
2. docker/.env — the primary operator config file (always loaded last, takes precedence)
3. Hardcoded environment: block defaults in docker-compose.yaml (fallback when a variable is absent from all env files)

Initial setup: cp docker/.env.example docker/.env, then edit docker/.env. No other files need to be touched for a standard deployment 6.

Key Variables by Domain#

Security 7:

• SECRET_KEY — leave blank to auto-generate; must be set explicitly in production multi-instance deployments
• PLUGIN_DAEMON_KEY — shared secret between the API and plugin daemon; defaults are insecure and must be rotated in production 8
• PLUGIN_DIFY_INNER_API_KEY — inner API key for plugin-to-API callbacks 9

Workers 10:

• SERVER_WORKER_AMOUNT=1 — Gunicorn workers for the API; each blocks for the full duration of plugin daemon calls, so increase this for concurrent agent workloads 11
• CELERY_WORKER_AMOUNT=4 — async task workers

Database 12:

• DB_TYPE, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
• DB_PLUGIN_DATABASE=dify_plugin — separate database used exclusively by the plugin daemon 13; must exist before the daemon starts

Plugin daemon 14:

• PLUGIN_DAEMON_URL=http://plugin_daemon:5002 — use the Docker service name, not localhost 11
• PLUGIN_MAX_EXECUTION_TIMEOUT=600 — per-plugin execution timeout (seconds)
• PLUGIN_STORAGE_TYPE=local — plugin file storage backend (local, S3, Azure, Aliyun OSS, Tencent COS, Volcengine TOS) 15
• PLUGIN_INSTALLED_PATH=plugin — relative subdir under PLUGIN_STORAGE_LOCAL_ROOT for installed plugins 16
• FORCE_VERIFYING_SIGNATURE=true — enforce plugin signature verification 17

The entire plugin daemon storage tree binds to ./volumes/plugin_daemon → /app/storage inside the container 5.

Nginx 18:

• NGINX_HTTPS_ENABLED, NGINX_PORT=80, NGINX_SSL_PORT=443, NGINX_CLIENT_MAX_BODY_SIZE=100M

Upgrade Procedure#

The canonical sequence for any major version bump:

1 — Pull and restart#

cd docker
git pull
docker compose pull
docker compose up -d

2 — Run database schema migration#

flask upgrade-db applies Alembic migrations to the main dify database using a Redis-backed distributed lock (60 s TTL, auto-renewing heartbeat) to prevent concurrent migration races 19:

docker compose exec api flask upgrade-db

With MIGRATION_ENABLED=true (the default), the API container also runs this automatically on startup 20. In multi-instance setups, only one pod acquires the lock; others skip migration silently.

3 — Run plugin backfill#

After schema migration, populate missing per-category auto-upgrade strategy rows for all tenants 21 22:

docker compose exec api flask backfill-plugin-auto-upgrade

Supports --dry-run, --tenant-id, --limit, and --batch-size flags. See api/commands/plugin.py for the implementation.

4 — Verify plugin daemon version#

The plugin daemon is versioned in lockstep with the Dify API. Protocol changes between releases cause complete communication failure if versions diverge 23:

The image tag in the current compose file is langgenius/dify-plugin-daemon:0.6.3-local 24. Confirm the running daemon image matches the Dify API version before proceeding.

5 — Clean stale plugin directories#

On startup the daemon scans PLUGIN_INSTALLED_PATH and logs record not found for any directory whose version identifier lacks a matching database row. Remove stale subdirectories from ./volumes/plugin_daemon/plugin/ once plugins are confirmed working in the UI 5.

Known Upgrade Failure Patterns#

See Plugin Database Integrity for full diagnostic queries and SQL recovery scripts.

Key Source Files#