Server Deployment Configuration#

Dify's API server (api/) runs in one of two modes, selected at container startup by the DEBUG environment variable. The switch lives in api/docker/entrypoint.sh.

DEBUG vs. Production Mode#

Debug mode (DEBUG=true) runs python -m app, which boots a gevent.pywsgi.WSGIServer directly. Because the process runs as __main__, it also applies gevent monkey-patching and patches gRPC/psycopg before any other import 1. This path is not suitable for production.

Production mode (DEBUG=false) launches Gunicorn with a GeventWebSocketWorker worker class, which supports WebSocket connections needed by Dify's streaming responses.

Gunicorn Startup Command#

The full command used in production 2:

gunicorn \
  --no-control-socket \
  --bind "${DIFY_BIND_ADDRESS:-0.0.0.0}:${DIFY_PORT:-5001}" \
  --workers ${SERVER_WORKER_AMOUNT:-1} \
  --worker-class ${SERVER_WORKER_CLASS:-geventwebsocket.gunicorn.workers.GeventWebSocketWorker} \
  --worker-connections ${SERVER_WORKER_CONNECTIONS:-10} \
  --timeout ${GUNICORN_TIMEOUT:-360} \
  app:socketio_app

Tunable Environment Variables#

Defaults from docker/.env.example:

Production sizing note: The default of 1 worker + 10 connections is intentionally conservative. Each Gunicorn worker holds its connection to the plugin daemon for the full duration of a call (up to PLUGIN_DAEMON_TIMEOUT, default 600 s). Under concurrent agent workloads, a single worker can starve all other API requests. See Worker Exhaustion Under Concurrent Load for a detailed analysis. The minimum recommended starting point is SERVER_WORKER_AMOUNT=4 or CPU core count 3.

gevent Patching in Gunicorn#

Gunicorn's gevent worker applies monkey-patching automatically. api/gunicorn.conf.py 4 adds a post_patch hook that subscribes to GeventDidPatchBuiltinModulesEvent to initialize gRPC gevent support and patch psycopg2 after the stdlib is patched. This ordering is required — calling grpc_gevent.init_gevent() before patching causes deadlocks 5.

The app.py module-level code does not apply monkey-patching when loaded by Gunicorn; patching is handled entirely by the worker class and gunicorn.conf.py 6.

Key Files#