Introduction to Dify

Relevant source files

• README.md
• api/.env.example
• api/app.py
• api/app_factory.py
• api/commands.py
• api/configs/feature/__init__.py
• api/configs/middleware/__init__.py
• api/configs/packaging/__init__.py
• api/controllers/console/datasets/datasets.py
• api/core/rag/datasource/vdb/vector_factory.py
• api/core/rag/datasource/vdb/vector_type.py
• api/pyproject.toml
• api/schedule/queue_monitor_task.py
• api/tests/unit_tests/configs/test_dify_config.py
• api/uv.lock
• dev/pytest/pytest_vdb.sh
• docker/.env.example
• docker/README.md
• docker/certbot/README.md
• docker/certbot/docker-entrypoint.sh
• docker/certbot/update-cert.template.txt
• docker/dify-env-sync.sh
• docker/docker-compose-template.yaml
• docker/docker-compose.middleware.yaml
• docker/docker-compose.png
• docker/docker-compose.yaml
• docker/middleware.env.example
• docker/nginx/conf.d/default.conf.template
• docker/nginx/docker-entrypoint.sh
• docker/nginx/https.conf.template
• web/package.json

Purpose and Scope

This document provides a high-level introduction to the Dify platform, covering its purpose, architecture, core components, and deployment options. For detailed technical architecture, see System Architecture Overview. For specific subsystems like the RAG pipeline or workflow engine, see sections 4 and 5 respectively.

Sources: README.md1-200

What is Dify?

Dify is an open-source platform for developing LLM (Large Language Model) applications. It combines agentic AI workflows, RAG (Retrieval-Augmented Generation) pipelines, agent capabilities, model management, and observability features into a unified development environment. The platform supports rapid prototyping and production deployment of AI applications through both a visual interface and programmatic APIs.

Key Characteristics:

• Multi-tenancy: Workspace-based isolation with role-based access control
• Model Agnostic: Supports 100+ LLM models from various providers (OpenAI, Anthropic, etc.)
• Extensible: Plugin system, custom tools, and API-based integrations
• Production-Ready: Built-in observability, quota management, and enterprise features

Sources: README.md63-114 api/pyproject.toml1-10

Edition Types

Dify is available in multiple editions:

Edition	Description	Deployment
Dify Cloud	Hosted SaaS offering with 200 free GPT-4 calls in sandbox plan	https://dify.ai
Self-Hosted (Community)	Open-source edition for self-deployment	Docker Compose, Kubernetes
Enterprise	Additional features including SSO, custom branding, advanced permissions	Self-hosted or managed

Sources: README.md116-128 docker/.env.example1-50

High-Level Service Architecture

Architecture Notes:

1. Single Entry Point: All traffic flows through Nginx, which routes based on URL paths
2. Service Separation: The langgenius/dify-api image runs in three modes controlled by the MODE environment variable:
   • MODE=api: HTTP API service (Flask/Gunicorn)
   • MODE=worker: Background task processor (Celery)
   • MODE=beat: Scheduled task scheduler (Celery Beat)
3. Database Flexibility: Supports PostgreSQL (default) or MySQL via DB_TYPE configuration
4. Vector Store Options: 30+ vector database options via VECTOR_STORE setting (Weaviate shown as default)

Sources: docker/docker-compose.yaml1-700 docker/docker-compose-template.yaml1-300 docker/nginx/conf.d/default.conf.template1-50

Core Service Components

API Service (api)

The main application server exposing REST APIs for both console (admin) and service (public) endpoints.

Key Components:

• Entry Point: api/app.py1-38
• Factory: api/app_factory.py18-70 - Creates Flask app with DifyApp class
• Configuration: api/configs/feature/__init__.py1-250 - Pydantic-based config system
• Startup Mode: Environment variable MODE=api

API Routing:

• /console/api/* - Admin console APIs (requires authentication)
• /api/* - Service APIs for app end-users
• /v1/* - OpenAI-compatible API endpoints

Sources: api/app.py1-38 api/app_factory.py1-100 docker/nginx/conf.d/default.conf.template7-20

Worker Service (worker)

Background task processor using Celery for asynchronous operations.

Task Types:

• Dataset indexing and document processing
• Workflow execution
• Email notifications
• Scheduled cleanup operations

Configuration:

• Broker: Redis (CELERY_BROKER_URL=redis://:password@redis:6379/1)
• Worker Count: Controlled by CELERY_WORKER_AMOUNT (default: 1)
• Autoscaling: Optional via CELERY_AUTO_SCALE=true

Sources: docker/.env.example371-391 docker/docker-compose-template.yaml64-100

Worker Beat (worker_beat)

Celery Beat scheduler for periodic tasks.

Scheduled Tasks:

• Queue monitoring api/schedule/queue_monitor_task.py1-50
• Log cleanup
• Expired token removal
• Workflow run archival

Sources: docker/docker-compose-template.yaml102-131 api/schedule/queue_monitor_task.py1-80

Web Service (web)

Next.js 16 + React 19 frontend application.

Key Details:

• Package Manager: pnpm 10.27.0 web/package.json6
• Node Version: >=24 web/package.json26
• Build Process: web/package.json32 - Standalone output for production
• Environment Variables:
  • CONSOLE_API_URL - Backend API URL
  • APP_API_URL - WebApp API URL

Sources: web/package.json1-60 docker/docker-compose-template.yaml133-161

Sandbox Service (sandbox)

Isolated code execution environment built in Go.

Features:

• Python/JavaScript code execution in restricted environment
• Network access via SSRF proxy
• Configurable timeout (SANDBOX_WORKER_TIMEOUT=15)
• API key authentication (SANDBOX_API_KEY)

Sources: docker/docker-compose-template.yaml247-269 api/configs/feature/__init__.py103-192

Plugin Daemon Service (plugin_daemon)

Go-based service for plugin management and execution.

Key Configuration:

• Image: langgenius/dify-plugin-daemon:0.5.3-local
• Port: 5002
• Database: Separate PostgreSQL database (DB_PLUGIN_DATABASE=dify_plugin)
• Communication: Authenticated via SERVER_KEY

Sources: docker/docker-compose-template.yaml271-300 docker/.env.example589-608

Data Layer Components

Primary Database

Options:

1. PostgreSQL 15 (default): docker/docker-compose-template.yaml163-197

   • Service name: db_postgres
   • Default credentials: postgres/difyai123456
   • Performance tuning: max_connections, shared_buffers, work_mem

2. MySQL 8.0: docker/docker-compose-template.yaml199-227

   • Service name: db_mysql
   • Requires DB_TYPE=mysql configuration

ORM: SQLAlchemy 2.0 with connection pooling api/pyproject.toml80

Sources: docker/.env.example232-308 docker/docker-compose-template.yaml163-227

Cache & Message Queue

Redis 6 - Used for multiple purposes:

• HTTP session storage
• Pub/sub for real-time updates
• Celery broker (database 1)
• Application cache (database 0)

Configuration:

• REDIS_HOST=redis
• REDIS_PORT=6379
• REDIS_PASSWORD=difyai123456

Advanced Features:

• Sentinel mode support for HA docker/.env.example353-363
• Cluster mode support docker/.env.example365-369

Sources: docker/.env.example332-391 docker/docker-compose-template.yaml229-245

Vector Databases

Dify supports 30+ vector database options via the VECTOR_STORE configuration:

Type	Configuration Key	Default Port	Use Case
Weaviate	weaviate	8080	Default, full-featured
Qdrant	qdrant	6333	High performance
Milvus	milvus	19530	Large scale
PGVector	pgvector	5432	PostgreSQL extension
Chroma	chroma	8000	Local development
Elasticsearch	elasticsearch	9200	Full-text search

Vector Store Factory: api/core/rag/datasource/vdb/vector_factory.py38-70 Vector Types Enum: api/core/rag/datasource/vdb/vector_type.py4-37

Sources: docker/.env.example536-708 api/core/rag/datasource/vdb/vector_type.py1-37 api/core/rag/datasource/vdb/vector_factory.py38-150

Configuration System

Environment-Based Configuration

Dify uses a layered configuration system built on Pydantic Settings:

Configuration Classes:

• DifyConfig: Root configuration class api/configs/app_config.py
• FeatureConfig: Application features api/configs/feature/__init__.py1-250
• MiddlewareConfig: Database, Redis, Storage api/configs/middleware/__init__.py1-150
• SecurityConfig: Auth, tokens, rate limiting api/configs/feature/__init__.py20-76

Validation: Pydantic performs automatic type checking and validation at startup

Sources: api/configs/app_config.py api/configs/feature/__init__.py1-250 docker/.env.example1-200

Key Configuration Categories

Category	Environment Variables	Purpose
Server	DIFY_PORT, SERVER_WORKER_AMOUNT, GUNICORN_TIMEOUT	API service configuration
Database	DB_TYPE, DB_HOST, DB_PORT, DB_DATABASE	Primary database connection
Cache	REDIS_HOST, REDIS_PASSWORD, CELERY_BROKER_URL	Redis configuration
Storage	STORAGE_TYPE, OPENDAL_SCHEME, S3_*, AZURE_*	File storage backend
Vector DB	VECTOR_STORE, WEAVIATE_*, QDRANT_*, etc.	Vector database selection
Security	SECRET_KEY, ACCESS_TOKEN_EXPIRE_MINUTES	Authentication & encryption
Features	CODE_EXECUTION_ENDPOINT, PLUGIN_DAEMON_URL	Service endpoints

Sources: docker/.env.example1-700 api/configs/feature/__init__.py1-250

Deployment Models

Docker Compose (Recommended)

Quick Start:

Files:

• Main Compose: docker/docker-compose.yaml1-1200 - Auto-generated from template
• Template: docker/docker-compose-template.yaml1-800 - Source template
• Middleware: docker/docker-compose.middleware.yaml1-300 - Separate middleware stack

Profiles:

• postgresql - Use PostgreSQL (default)
• mysql - Use MySQL instead
• certbot - Enable automatic SSL certificate management

Sources: README.md72-83 docker/README.md1-100

Kubernetes

Community-contributed Helm Charts available:

• Helm Chart by @LeoQuote (Douban)
• Helm Chart by @BorisPolonsky
• YAML manifests by @Zhoneym

Sources: README.md162-171

Cloud Platforms

Terraform Support:

• Azure Global
• Google Cloud
• AWS (via CDK)
• Alibaba Cloud (Computing Nest)

Sources: README.md172-196

System Requirements

Minimum Requirements

Component	Specification
CPU	>= 2 Cores
RAM	>= 4 GiB
Docker	Docker 20.10+
Docker Compose	v2.0+
Python	3.11-3.12 (for API)
Node.js	>= 24 (for Web)

Sources: README.md67-70 api/pyproject.toml4 web/package.json25-26

Python Dependencies

Core Framework:

• Flask 3.1.2 - Web framework
• Celery 5.5.2 - Task queue
• SQLAlchemy 2.0.29 - ORM
• Pydantic 2.11.4 - Data validation

LLM Integration:

• litellm 1.77.1 - Unified LLM API
• tiktoken 0.9.0 - Token counting
• transformers 4.56.1 - Model loading

Full dependency list: api/pyproject.toml6-97

Sources: api/pyproject.toml1-100

Node.js Dependencies

Core Framework:

• next: 16.1.5
• react: 19.2.4
• react-dom: 19.2.4

State Management:

• zustand: 5.0.9
• jotai: 2.16.1

Full dependency list: web/package.json60-165

Sources: web/package.json1-165

Storage Architecture

Dify supports multiple storage backends through a unified interface:

Configuration Example (OpenDAL with S3):

Supported Backends:

• OpenDAL (default) - Unified interface supporting 30+ storage services
• AWS S3 / S3-compatible (MinIO, Cloudflare R2)
• Azure Blob Storage
• Google Cloud Storage
• Alibaba Cloud OSS
• Tencent COS
• Huawei OBS, Baidu OBS, Volcengine TOS
• Supabase Storage

Sources: docker/.env.example411-535 api/configs/middleware/__init__.py53-100

Command-Line Interface

Dify provides administrative commands via Flask CLI:

Available Commands: api/commands.py58-500

Dataset Management:

Sources: api/commands.py1-700

Key Architectural Patterns

Multi-Tenancy

All resources are scoped to a Tenant (workspace):

• Tenant Model: models/Tenant
• Resource Scoping: All database tables include tenant_id foreign key
• Access Control: Role-based permissions (Owner, Admin, Editor, Dataset Operator)
• Data Isolation: Complete separation at database query level

Event-Driven Architecture

Celery-based async processing for:

• Document indexing tasks/dataset_indexing_task.py
• Workflow execution tasks/workflow_execution_tasks.py
• Email notifications
• Cleanup operations

Plugin System

Extensibility through plugin daemon:

• Plugin Types: Model providers, tools, endpoints, triggers
• Execution: Separate Go service with sandboxed execution
• Communication: gRPC-based API between API service and plugin daemon

Sources: docker/docker-compose-template.yaml271-300 api/configs/feature/__init__.py221-275

Next Steps

For deeper technical details:

• Architecture Details: See System Architecture Overview
• Data Models: See Core Data Models and Domain Entities
• RAG System: See Knowledge Base and RAG System
• Workflow Engine: See Workflow Engine and Node Execution
• Deployment Guide: See Deployment and Operations

Sources: README.md1-200 docker/README.md1-150