Docker Networking#

Dify's Docker Compose stack uses Docker's embedded DNS resolver for inter-service communication: containers address each other by service name (e.g., api, plugin_daemon, redis), and Docker resolves those names to container IPs on a shared bridge network. All authoritative network definitions live in docker/docker-compose-template.yaml — the generated docker-compose.yaml must not be edited directly. 1

Network Topology#

The stack defines six named bridge networks 2:

Service → network membership 1:

┌─ default (external access) ───────────────────────────────────────────┐
│ nginx → api / api_websocket / worker / plugin_daemon / web │
│ redis db_postgres agent_backend agent_ssrf_proxy │
└───────────────────────────────────────────────────────────────────────┘
       │ ssrf_proxy_network (internal: true)
       ├── api, worker, worker_beat, api_websocket
       ├── plugin_daemon
       ├── ssrf_proxy (Squid :3128)
       └── sandbox ← only here

       agent_sandbox_network (internal: true)
       ├── agent_backend (also on default)
       └── local_sandbox ← shellctl :5004

       local_sandbox_proxy_network (internal: true)
       ├── agent_ssrf_proxy (also on default)
       └── local_sandbox ← proxy egress :3128

Key Inter-Service DNS Names and Ports#

All inter-service URLs use Docker DNS service names. Never use localhost for cross-container URLs — it resolves to the container itself, not a peer. The most common misconfiguration is PLUGIN_DAEMON_URL=http://localhost:5002 in a Docker deployment. 1

Key variables with defaults are set in docker/envs/core-services/shared.env.example — e.g., SSRF_PROXY_HTTP_URL=http://ssrf_proxy:3128 3, CODE_EXECUTION_ENDPOINT=http://sandbox:8194 4, CELERY_BROKER_URL=redis://:difyai123456@redis:6379/1 5.

Plugin Daemon Connectivity#

The plugin daemon requires two bidirectional HTTP paths 6:

1. API → Daemon (http://plugin_daemon:5002): all plugin invocations. Authenticated via PLUGIN_DAEMON_KEY (X-Api-Key header).
2. Daemon → API (http://api:5001): inner-API callbacks from the daemon. Authenticated via PLUGIN_DIFY_INNER_API_KEY.

Port 5002 is internal-only — not published to the Docker host. Port 5003 (debug/remote install) is the only plugin daemon port published externally by default 7. See also api/configs/feature/__init__.py for application-layer defaults.

In source/dev mode (daemon in Docker, API on host), set PLUGIN_DIFY_INNER_API_URL=http://host.docker.internal:5001 on macOS/Windows, or the host bridge IP on Linux. 1

web Service SSR Routing#

The Next.js web container's server-side rendering fetches data from the API over the internal network. SERVER_CONSOLE_API_URL defaults to http://api:5001. If you override CONSOLE_API_URL with a public hostname for browser access, you must also explicitly set SERVER_CONSOLE_API_URL to the internal DNS name. Leaving it as a public hostname that doesn't resolve inside the container causes silent SSR failures. 1

Startup Ordering and Health Checks#

The web service has no depends_on entries — it starts immediately and may encounter ECONNREFUSED if the API container is not yet ready 8. The api service waits for init_permissions to complete, databases to become healthy, and redis / agent_backend to start 9. The api service exposes a healthcheck at http://localhost:5001/health (interval: 30s, start_period: 30s) 10. Transient ECONNREFUSED errors from the web container after a stack restart are expected until the api healthcheck passes; Docker's built-in restart policy (restart: always) recovers these automatically.

Key Source Files#