Principle:Langgenius Dify Service Orchestration

Knowledge Sources	Dify
Domains	DevOps, Deployment, Docker, Orchestration
Last Updated	2026-02-12 00:00 GMT

Overview

Service Orchestration is the principle of defining the complete Dify application stack as a declarative Docker Compose specification with dependency ordering, health checks, and network isolation.

Description

The Dify platform consists of multiple cooperating services that must start in the correct order and communicate through well-defined network boundaries. The docker-compose.yaml file declaratively describes every service, its dependencies, health checks, volumes, exposed ports, and network memberships.

The core services in the Dify stack are:

init_permissions -- Busybox init container that sets storage volume ownership (runs once, then exits).
api -- Flask application served by Gunicorn with gevent workers on port 5001. Handles all REST API requests. Uses image langgenius/dify-api:1.13.0 with MODE=api.
worker -- Celery worker using the same image as api but with MODE=worker. Processes background tasks for datasets, workflows, mail, and more.
worker_beat -- Celery Beat scheduler using MODE=beat. Triggers periodic tasks on a configurable schedule.
web -- Next.js frontend served by PM2 (image langgenius/dify-web:1.13.0). Handles the console and web app UI.
nginx -- Reverse proxy that routes HTTP/HTTPS traffic to the api and web services. Exposes ports 80 and 443.
db_postgres (or db_mysql) -- Metadata database, activated via Docker Compose profiles.
redis -- Redis 6 for caching and as the Celery message broker.
sandbox -- DifySandbox for safe code execution, connected through the SSRF proxy network.
plugin_daemon -- Plugin management daemon that communicates with the API via an internal API key.
ssrf_proxy -- Squid-based proxy that restricts outbound network access from the sandbox for SSRF protection.
Vector database -- One of many options (weaviate, qdrant, milvus, etc.), activated via profiles.

Key orchestration features include:

Dependency ordering -- depends_on with condition: service_healthy or condition: service_completed_successfully ensures databases are ready before the API starts.
Health checks -- PostgreSQL uses pg_isready, Redis uses redis-cli ping, and each vector database defines its own health probe.
Network isolation -- The ssrf_proxy_network is an internal bridge network that prevents the sandbox from directly accessing the internet. The api, worker, and ssrf_proxy services are members of both the default and SSRF proxy networks.
Shared configuration -- The x-shared-env YAML anchor avoids duplication of environment variables between the api and worker services.

Usage

Use this principle when:

Deploying the full Dify stack for the first time.
Debugging service startup failures or dependency issues.
Customizing port mappings, scaling workers, or adding TLS certificates.
Understanding how services communicate within the Docker network.

Theoretical Basis

Docker Compose orchestration follows a directed acyclic graph (DAG) of service dependencies. Each service node can depend on other services being either "started" or "healthy":

Pseudocode: Service startup DAG

init_permissions -> (completes)
db_postgres      -> (healthy: pg_isready)
redis            -> (started)

api    depends_on: init_permissions(completed), db_postgres(healthy), redis(started)
worker depends_on: init_permissions(completed), db_postgres(healthy), redis(started)

web    -> (no dependencies, starts immediately)
nginx  depends_on: api(started), web(started)

sandbox -> (starts independently on ssrf_proxy_network)
ssrf_proxy -> (starts independently, bridges ssrf_proxy_network and default)

plugin_daemon depends_on: db_postgres(healthy)

The network topology provides defense-in-depth:

Network layout:

[default network]
  api <-> worker <-> redis <-> db_postgres <-> plugin_daemon
  api <-> nginx <-> web

[ssrf_proxy_network] (internal, no internet)
  api <-> ssrf_proxy <-> sandbox
  worker <-> ssrf_proxy

[milvus network] (if milvus profile active)
  etcd <-> minio <-> milvus-standalone

Services on the ssrf_proxy_network cannot reach the internet directly because the network is declared with internal: true. The sandbox routes all outbound HTTP through the Squid proxy, which enforces URL filtering.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment