Docker Deployment and Upgrades#

Dify's primary self-hosted deployment is a Docker Compose stack under the docker/ directory. The stack is managed via docker/docker-compose.yaml, which is auto-generated from docker-compose-template.yaml — never edit it directly 1. All operator customization goes into docker/.env, copied from docker/.env.example.

As of v1.17.x, the stack includes seven core application services (api, api_websocket, worker, worker_beat, web, plugin_daemon, agent_backend) plus supporting infrastructure (db_postgres, redis, nginx, ssrf_proxy, agent_ssrf_proxy, sandbox, local_sandbox, init_permissions). Optional vector store backends and the WebSocket collaboration service are activated via COMPOSE_PROFILES in .env 1.

Prerequisites: CPU ≥ 2 cores, RAM ≥ 4 GiB, Docker ≥ 19.03, Docker Compose ≥ 2.24.0.

Initial Deployment#

git clone --branch <TAG> https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
# Edit .env — at minimum set SECRET_KEY
docker compose up -d

Navigate to http://localhost/install to complete setup. See the official quick-start guide for full details.

Environment Variable Management#

Variables resolve with this precedence (later wins) 1:

1. docker/.env — primary operator config
2. docker/envs/**/*.env — optional per-service overrides (see docker/envs/)
3. Hardcoded environment: defaults inside docker-compose.yaml

docker/.env.example is the canonical variable reference — diff it against your .env after every upgrade to catch newly required variables.

Key variables to verify on every deployment or upgrade:

Standard Upgrade Procedure#

The canonical sequence for any version bump 1:

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

Then run these post-start commands in order:

1. Apply schema migrations (auto-runs on startup when MIGRATION_ENABLED=true; run explicitly to confirm):

   ⧉

   docker compose exec api flask upgrade-db
   

   Implementation: api/commands/system.py

2. Backfill plugin auto-upgrade strategies — mandatory after 1.15.0+; must run after upgrade-db because it depends on the category column that migration adds 5:

   ⧉

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

   Implementation: api/commands/plugin.py

3. Verify plugin daemon image tag matches the Dify release (see Plugin Daemon Synchronization below).

4. Clean stale plugin directories — remove subdirectories in ./volumes/plugin_daemon/plugin/ that log record not found in the daemon, after confirming plugins work in the UI 6.

Version-Specific Breaking Changes#

Standard docker compose up + flask upgrade-db is not sufficient for the following upgrades. The Release Breaking Changes KB has the full catalog 4.

1.9.0 — Datasource Credential Migration#

After upgrading, run 7:

docker compose exec api flask transform-datasource-credentials

Users on v2.0.0-beta.1/beta.2 face a destructive migration that deletes all existing Knowledge Pipelines and Dataset Credentials.

1.13.0 — New Celery Queue#

A new workflow_based_app_execution Celery queue is required for Human-in-the-Loop workflows and workflow-based streaming 8. If you use a custom CELERY_QUEUES, explicitly add workflow_based_app_execution (and api_token if ENABLE_API_TOKEN_LAST_USED_UPDATE_TASK=true). New PubSub env vars (PUBSUB_REDIS_URL, PUBSUB_REDIS_CHANNEL_TYPE) were also introduced in this release.

1.14.x — model_type Enum Rename#

Three enum values were renamed without an automatic data migration 4:

Symptom: UI shows "Credentials unavailable"; HTTP 400 "Credential with id … not found" in the browser console. Inference still works; management operations (view, edit, delete) are broken.

Fix: Run the CLI migration 4:

docker compose exec api flask data-migrate legacy-model-types # dry-run
docker compose exec api flask data-migrate legacy-model-types --apply

Implementation: api/commands/data_migrate.py and api/services/legacy_model_type_migration.py (five affected tables: provider_models, provider_model_credentials, tenant_default_models, provider_model_settings, load_balancing_model_configs).

Note: From Alembic migration 2026_08_27_1200-5578e028b2f2 (PR #41326) onward, flask upgrade-db applies this automatically 4.

1.14.x — Duplicate plugin_unique_identifier#

When upgrading from 1.13.x, the daemon may restart in a loop (SQLSTATE 23505) because a unique index creation fails on dify_plugin.plugins. Diagnose with:

SELECT plugin_unique_identifier, COUNT(*) AS cnt
  FROM plugins
  GROUP BY plugin_unique_identifier
  HAVING COUNT(*) > 1;

Remove extra rows (keep the most recent), then restart the daemon. See Issue #38276 6.

1.15.0 — Multiple Breaking Changes#

1. DB_TYPE now required — add DB_TYPE=postgresql to .env 4.

2. SSRF proxy deny-by-default — blocks all RFC-1918 private IPs and all destinations except .marketplace.dify.ai. Workflow HTTP-request nodes calling internal endpoints will return 403 Forbidden 4. Fix by adding to .env and restarting:

   ⧉

   SSRF_PROXY_ALLOW_PRIVATE_DOMAINS=internal.mycompany.com,ollama
   SSRF_PROXY_ALLOW_PRIVATE_IPS=10.10.5.42,192.168.1.0/24
   

   ⧉

   docker compose restart ssrf_proxy
   

   Config template: docker/ssrf_proxy/squid.conf.template. The entrypoint docker/ssrf_proxy/docker-entrypoint.sh injects these as Squid ACL fragments at startup.

3. Legacy model type migration — flask upgrade-db alone is not sufficient; also run flask data-migrate legacy-model-types --apply for pre-1.15.0 databases 9.

4. Plugin backfill — flask backfill-plugin-auto-upgrade is now mandatory after every upgrade.

1.17.0 — EDITION → DEPLOYMENT_EDITION Rename#

Rename this variable in .env before starting services 10. Removed variables include AGENT_BACKEND_RUN_TIMEOUT_SECONDS, ENTERPRISE_ENABLED, and DIFY_AGENT_SHELLCTL_*. Timeout defaults for APP_MAX_EXECUTION_TIME and WORKFLOW_MAX_EXECUTION_TIME changed from 1200 s to 3600 s.

Plugin Daemon Synchronization#

The plugin daemon is a separate Go-based service that must stay in version lockstep with the Dify API. Protocol mismatches cause complete communication failure — the daemon logs "failed to find the version of the plugin sdk" and the API returns connection errors 3.

The daemon communicates with the API at http://plugin_daemon:5002 — always use the Docker service name, not localhost 3. It maintains a separate PostgreSQL database (dify_plugin, configurable via DB_PLUGIN_DATABASE) that must exist before the daemon starts 1.

Plugin storage bind-mounts ./volumes/plugin_daemon → /app/storage. Back up this directory to preserve installed plugins across host restarts.

For plugin DB integrity issues (version reconciliation, duplicate identifiers, daemon schema init failures), see the Plugin Database Integrity KB 6 and Plugin Daemon Architecture KB 3.

Key Files and References#