TechSetupGuides
Intermediateaillmworkflowagentsragpythonreactnextjspostgresredisceleryvector-database

Dify: Production-ready agentic workflow platform

Build, deploy, and manage AI-powered agents and workflows with visual interface, RAG pipeline, comprehensive model support, and LLMOps capabilities.

  1. Step 1

    What is Dify?

    Dify is an open-source LLM application development platform that combines AI workflow orchestration, RAG pipeline, agent capabilities, model management, and observability features. With 142,000+ GitHub stars, Dify provides an intuitive visual interface for building production-ready AI applications, supporting everything from prototype to deployment. It offers both cloud-hosted and self-hosted options, making it suitable for startups and enterprises alike.

  2. Step 2

    Technology stack overview

    Dify is built on a robust microservices architecture with clear separation between frontend, backend, and infrastructure layers:

    Backend (Python):

    • Python 3.12 with uv package manager
    • Flask 3.1+ as the web framework
    • Gunicorn + Gevent for WSGI server and async support
    • Celery for background task processing
    • SQLAlchemy ORM with PostgreSQL or MySQL
    • Redis for caching and message broker
    • WebSocket support via python-socketio

    Frontend (Next.js):

    • Next.js 15+ with React 19
    • TypeScript 5
    • pnpm workspace monorepo
    • Tailwind CSS 4 for styling
    • TanStack Query for data fetching
    • Zustand for state management
    • Jotai for atomic state
    • ReactFlow (via elkjs) for visual workflow editor
    • Monaco Editor for code editing

    Infrastructure:

    • PostgreSQL or MySQL for relational data
    • Redis for caching and Celery broker
    • Nginx for reverse proxy and static files
    • Docker and Docker Compose for containerization
    • Multiple vector database options (Qdrant, Weaviate, Chroma, Milvus, PgVector, etc.)
    • Optional: MinIO for object storage, Etcd for distributed config
    Backend Architecture:
├── Python 3.12 + uv
├── Flask 3.1+ (web framework)
├── Gunicorn + Gevent (WSGI + async)
├── Celery (task queue)
├── SQLAlchemy (ORM)
├── PostgreSQL/MySQL (database)
└── Redis (cache + broker)

Frontend Stack:
├── Next.js 15+ (React 19)
├── TypeScript 5
├── pnpm (package manager)
├── Tailwind CSS 4
├── TanStack Query (data)
├── Zustand + Jotai (state)
├── ReactFlow (workflow canvas)
└── Monaco Editor (code)

Infrastructure:
├── Nginx (reverse proxy)
├── Docker + Docker Compose
├── Vector DBs (Qdrant, Weaviate, etc.)
├── MinIO (object storage)
└── Etcd (distributed config)
  3. Step 3

    Core features and capabilities

    Dify provides a comprehensive platform for building LLM applications:

    1. Visual Workflow Builder: Drag-and-drop interface for creating AI workflows on a visual canvas. Connect LLMs, tools, data sources, and custom logic without writing boilerplate code.

    2. Comprehensive Model Support: Seamless integration with hundreds of LLMs from dozens of providers - OpenAI, Anthropic, Google, Mistral, Llama, and any OpenAI-compatible API.

    3. Prompt IDE: Intuitive interface for crafting prompts, comparing model performance, and adding features like text-to-speech to chat applications.

    4. RAG Pipeline: Complete RAG capabilities from document ingestion to retrieval, with out-of-box support for PDFs, PPTs, and common document formats. Includes text extraction, chunking, and vector indexing.

    5. Agent Capabilities: Define agents based on LLM Function Calling or ReAct patterns. Includes 50+ built-in tools (Google Search, DALL·E, Stable Diffusion, WolframAlpha) and support for custom tools.

    6. LLMOps: Monitor and analyze application logs and performance over time. Continuously improve prompts, datasets, and models based on production data and annotations.

    7. Backend-as-a-Service: All features come with corresponding REST APIs, enabling easy integration into existing applications.

  4. Step 4

    Prerequisites

    Before installing Dify, ensure your system meets these requirements:

    Minimum hardware:

    • CPU: 2 cores or more
    • RAM: 4 GiB or more
    • Disk: 10 GB available space

    Software requirements:

    • Docker 20.10+ and Docker Compose 2.0+
    • For source installation: Python 3.12, Node.js 20.19+, pnpm 9+

    Recommended for production:

    • CPU: 4+ cores
    • RAM: 8+ GiB
    • PostgreSQL 15+ (external, not dockerized)
    • Redis 7+ (external, managed)
    • Vector database of choice (Qdrant, Weaviate, etc.)
    # Verify Docker installation
docker --version
docker compose version

# For source installation, verify Python and Node
python --version  # Should be 3.12.x
node --version    # Should be 20.19+
pnpm --version    # Should be 9+
  5. Step 5

    Quick start with Docker Compose

    The fastest way to get Dify running is with Docker Compose. This method includes all required services (PostgreSQL, Redis, Nginx, vector DB) in a single stack:

    # Clone the repository
git clone https://github.com/langgenius/dify.git
cd dify

# Navigate to docker directory
cd docker

# Copy environment template
cp .env.example .env

# Start all services
docker compose up -d

# Access Dify at http://localhost/install
# Follow the web-based setup wizard
  6. Step 6

    Environment configuration

    Dify uses environment variables for configuration. The .env file in the docker/ directory controls all settings. Key configuration areas:

    Core settings:

    • SECRET_KEY: Encryption key for security (auto-generated or set manually)
    • CONSOLE_WEB_URL: URL for the admin console
    • APP_WEB_URL: URL for end-user applications
    • EDITION: Set to SELF_HOSTED or CLOUD

    Database settings:

    • DB_TYPE: Choose postgres or mysql
    • DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE

    Redis settings:

    • REDIS_HOST, REDIS_PORT, REDIS_PASSWORD
    • REDIS_USE_SSL: Enable for secure connections

    Vector database settings:

    • VECTOR_STORE: Choose from qdrant, weaviate, milvus, pgvector, chroma, etc.
    • Provider-specific settings in docker/envs/vectorstores/

    Storage settings:

    • STORAGE_TYPE: local, s3, azure-blob, google-storage, aliyun-oss
    • Provider-specific credentials for cloud storage
    # Essential .env configuration
SECRET_KEY=your-secret-key-here
CONSOLE_WEB_URL=http://localhost
APP_WEB_URL=http://localhost

# Database
DB_TYPE=postgres
DB_HOST=db_postgres
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your-password
DB_DATABASE=dify

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password

# Vector Store (example: Qdrant)
VECTOR_STORE=qdrant
QDANT_URL=http://qdrant:6333

# After editing .env, restart services
docker compose down
docker compose up -d
  7. Step 7

    Production deployment considerations

    For production deployments, consider these best practices:

    1. External databases: Use managed PostgreSQL and Redis services instead of Docker containers for better reliability, backups, and scaling.

    2. Load balancing: Deploy multiple API and worker containers behind a load balancer. The architecture supports horizontal scaling.

    3. Vector database: Choose based on your scale - Qdrant for general use, Weaviate for hybrid search, Milvus for massive scale, PgVector for simplicity.

    4. Object storage: Use cloud object storage (S3, Azure Blob, GCS) instead of local filesystem for file uploads and generated content.

    5. SSL/TLS: Configure Nginx with SSL certificates. Use Certbot for Let's Encrypt automation.

    6. Monitoring: Enable OpenTelemetry instrumentation for observability. Integrate with Langfuse, Langsmith, or Arize Phoenix for LLM-specific monitoring.

    7. Resource limits: Configure appropriate CPU and memory limits for each service based on your workload.

    # Example production .env with external services
DB_TYPE=postgres
DB_HOST=your-rds-endpoint.amazonaws.com
DB_PORT=5432
DB_SSL_ENABLED=true

REDIS_HOST=your-elasticache.amazonaws.com
REDIS_PORT=6379
REDIS_USE_SSL=true

STORAGE_TYPE=s3
S3_BUCKET_NAME=your-bucket
S3_REGION=us-east-1

VECTOR_STORE=qdrant
QDANT_URL=https://your-qdrant-cloud-url
QDANT_API_KEY=your-api-key
  8. Step 8

    Development setup from source

    For contributors or those needing to customize Dify, you can run from source code. This requires both Python and Node.js development environments:

    # Clone repository
git clone https://github.com/langgenius/dify.git
cd dify

# Backend setup (Python 3.12 required)
cd api

# Install uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

# Set up database (requires PostgreSQL running)
flask db upgrade

# Start backend (in api/ directory)
flask run --host 0.0.0.0 --port 5001 --debug

# In a new terminal: Frontend setup
cd web
pnpm install
pnpm dev  # Runs on http://localhost:3000

# In a new terminal: Start Celery worker
cd api
celery -A celery_entrypoint worker -Q dataset,generation,mail,ops_trace -P gevent -c 1 --loglevel INFO
  9. Step 9

    Kubernetes deployment

    Dify can be deployed to Kubernetes for high availability and scalability. The community provides several Helm charts:

    Available Helm charts:

    Terraform deployments:

    For Kubernetes deployments, externalize databases, use persistent volumes for storage, and configure proper resource requests/limits.

    # Example using a Helm chart
helm repo add douban https://douban.github.io/charts/
helm repo update

# Install with custom values
helm install dify douban/dify \
  --set postgresql.enabled=false \
  --set externalDatabase.host=your-db-host \
  --set redis.enabled=false \
  --set externalRedis.host=your-redis-host \
  --namespace dify \
  --create-namespace
  10. Step 10

    Vector database options

    Dify supports 30+ vector database backends. Choose based on your requirements:

    For getting started:

    • Qdrant: Easy to use, good performance, Docker-ready
    • Chroma: Lightweight, embedded option
    • Weaviate: Feature-rich with hybrid search

    For production scale:

    • Milvus: Massive scale, cloud-native
    • Elasticsearch/OpenSearch: If already in your stack
    • PgVector: PostgreSQL extension, simplifies deployment

    Cloud-managed options:

    • Qdrant Cloud
    • Weaviate Cloud
    • Pinecone
    • Upstash Vector
    • Many enterprise options (Alibaba Cloud, Tencent, Baidu, etc.)

    Chinese cloud providers and specialized databases are also supported (OceanBase, TiDB Vector, AnalyticDB, etc.).

    # Configure vector store in .env
VECTOR_STORE=qdrant  # or weaviate, milvus, pgvector, chroma

# For Qdrant (local Docker)
QDANT_URL=http://qdrant:6333

# For Qdrant Cloud
QDANT_URL=https://your-cluster.aws.cloud.qdrant.io
QDANT_API_KEY=your-api-key

# For PgVector (using same PostgreSQL)
VECTOR_STORE=pgvector
PGVECTOR_HOST=${DB_HOST}
PGVECTOR_PORT=${DB_PORT}
PGVECTOR_USER=${DB_USERNAME}
PGVECTOR_PASSWORD=${DB_PASSWORD}
PGVECTOR_DATABASE=${DB_DATABASE}
  11. Step 11

    Model provider configuration

    Dify supports hundreds of LLMs from dozens of providers. Configure providers in the admin console or via environment variables:

    Major providers supported:

    • OpenAI (GPT-4, GPT-3.5)
    • Anthropic (Claude models)
    • Google (Gemini, PaLM)
    • Azure OpenAI
    • AWS Bedrock
    • Cohere
    • Mistral AI
    • Hugging Face
    • Local models via Ollama, LocalAI, Xinference
    • Any OpenAI-compatible API

    Configuration methods:

    1. Web UI: Admin Console → Settings → Model Providers
    2. Environment variables for system-wide defaults
    3. Per-app model selection in workflow builder
    # Example: Configure OpenAI in .env
OPENAI_API_KEY=sk-...

# Example: Configure Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Example: Configure Azure OpenAI
AZURE_OPENAI_API_KEY=your-key
AZURE_OPENAI_API_BASE=https://your-resource.openai.azure.com
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# Example: Use local Ollama
# In admin console, add custom model provider:
# Base URL: http://host.docker.internal:11434
# Model: llama3, mistral, etc.
  12. Step 12

    Observability and monitoring

    Dify includes built-in observability and integrates with major LLM monitoring platforms:

    Built-in features:

    • Application logs and audit trails
    • Message logs with token usage
    • User conversation history
    • Annotation and feedback collection
    • Performance metrics

    Third-party integrations:

    • Langfuse: Open-source LLM engineering platform
    • Langsmith: LangChain's monitoring platform
    • Opik by Comet: ML observability
    • Arize Phoenix: ML observability and evaluation
    • MLflow: ML lifecycle management
    • Cloud-specific: Aliyun, Tencent Cloud

    OpenTelemetry support: Dify includes OpenTelemetry instrumentation for Flask, Celery, HTTP clients, Redis, and SQLAlchemy. Export traces to your preferred observability backend.

    # Enable Langfuse in .env
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_SECRET_KEY=sk-...
LANGFUSE_HOST=https://cloud.langfuse.com  # or self-hosted

# Enable OpenTelemetry
OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318
OTEL_SERVICE_NAME=dify

# View built-in monitoring
# Admin Console → Monitoring → Logs, Analytics, Annotations
  13. Step 13

    Plugin system

    Dify supports a plugin architecture for extending functionality:

    Plugin types:

    • Model providers: Add custom LLM integrations
    • Tools: Extend agent capabilities with custom tools
    • Vector stores: Support additional vector databases
    • Trace providers: Add custom observability integrations

    Plugin development: Plugins are Python packages installed via uv in the api/providers/ workspace. Each plugin registers entry points for discovery.

    Security: Plugins run in a sandboxed environment with configurable resource limits and network restrictions.

    # Plugin structure example (simplified)
# providers/custom-vdb/my_vectordb/
# ├── __init__.py
# ├── my_vectordb.py  # Implementation
# └── pyproject.toml  # Entry point registration

# In pyproject.toml:
[project.entry-points."dify.vector_backends"]
my_vectordb = "my_vectordb.my_vectordb:MyVectorDB"

# Install plugin
cd api
uv sync  # Automatically discovers and installs workspace plugins
  14. Step 14

    API usage and integration

    Dify exposes comprehensive REST APIs for integrating with external applications:

    API categories:

    • App APIs: Create and manage applications
    • Conversation APIs: Send messages, stream responses
    • Workflow APIs: Execute workflows programmatically
    • Dataset APIs: Manage knowledge bases and documents
    • Admin APIs: Manage users, settings, and resources

    Authentication:

    • API keys generated per application
    • Support for both user and anonymous access
    • Rate limiting and quota management

    SDKs available:

    • Python SDK: pip install dify-client
    • Node.js SDK: npm install dify-client
    • Official OpenAPI spec for custom client generation
    # Example: Using Dify Python SDK
from dify_client import DifyClient

# Initialize client
client = DifyClient(
    api_key="your-app-api-key",
    base_url="http://localhost/v1"
)

# Send a chat message
response = client.chat_messages.create(
    inputs={"query": "What is the weather today?"},
    user="user-123"
)

print(response.answer)

# Stream workflow execution
for event in client.workflows.run_stream(
    inputs={"input": "process this"},
    user="user-123"
):
    if event.event == "workflow_finished":
        print(event.data.outputs)
  15. Step 15

    Security best practices

    Follow these security recommendations for production deployments:

    1. Environment variables:

    • Never commit .env files to version control
    • Use strong, randomly generated SECRET_KEY
    • Rotate API keys and database credentials regularly

    2. Network security:

    • Enable SSL/TLS for all external connections
    • Use private networks for internal service communication
    • Configure SSRF proxy to prevent server-side request forgery
    • Implement rate limiting on API endpoints

    3. Database security:

    • Enable SSL for database connections
    • Use read-only replicas for analytics queries
    • Regular backups with encryption at rest

    4. Access control:

    • Implement role-based access control (RBAC)
    • Enable multi-factor authentication for admin accounts
    • Audit logs for security events

    5. Content security:

    • Configure content security policy (CSP) headers
    • Sanitize user inputs to prevent XSS
    • Validate file uploads and scan for malware
    # Generate strong secret key
SECRET_KEY=$(openssl rand -base64 42)

# Enable database SSL in .env
DB_SSL_ENABLED=true

# Configure SSRF proxy
SSRF_PROXY_HTTP_URL=http://ssrf_proxy:3128
SSRF_PROXY_HTTPS_URL=http://ssrf_proxy:3128

# Enable rate limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=60

# Configure CSP headers in Nginx
add_header Content-Security-Policy "default-src 'self';";
  16. Step 16

    Backup and disaster recovery

    Implement a comprehensive backup strategy for production systems:

    Database backups:

    • Daily automated backups of PostgreSQL/MySQL
    • Point-in-time recovery (PITR) enabled
    • Test restore procedures regularly
    • Store backups in different geographic regions

    File storage backups:

    • If using local storage, backup the volumes directory
    • Cloud object storage (S3, etc.) has built-in redundancy
    • Enable versioning for uploaded files

    Configuration backups:

    • Version control for .env and configuration files (without secrets)
    • Document custom configurations and integrations

    Disaster recovery plan:

    • Document RTO (Recovery Time Objective) and RPO (Recovery Point Objective)
    • Maintain runbooks for common failure scenarios
    • Test failover procedures
    • Keep infrastructure as code (Terraform, Helm charts) up to date
    # Example: PostgreSQL backup script
#!/bin/bash
DATETIME=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="dify_backup_${DATETIME}.sql.gz"

pg_dump -h localhost -U postgres dify | gzip > "${BACKUP_FILE}"

# Upload to S3
aws s3 cp "${BACKUP_FILE}" "s3://your-backup-bucket/dify/"

# Retain only last 30 days
find . -name "dify_backup_*.sql.gz" -mtime +30 -delete

# Restore example
gunzip -c dify_backup_20260527_120000.sql.gz | psql -h localhost -U postgres dify
  17. Step 17

    Scaling and performance optimization

    Optimize Dify for high-traffic production workloads:

    Horizontal scaling:

    • Scale API servers: Multiple containers behind load balancer
    • Scale workers: Deploy dedicated Celery workers for different queues
    • Separate workers by queue type: dataset, generation, mail, ops_trace

    Database optimization:

    • Connection pooling: Configure appropriate pool sizes
    • Read replicas for analytics and reporting
    • Database query optimization and indexing
    • Regular VACUUM and ANALYZE on PostgreSQL

    Caching strategy:

    • Redis for session caching
    • HTTP caching headers for static assets
    • Model response caching for repeated queries
    • Vector search result caching

    Resource allocation:

    • Set appropriate CPU and memory limits
    • Monitor resource usage and adjust
    • Use autoscaling based on metrics

    Content Delivery Network (CDN):

    • Serve static assets via CDN
    • Cache API responses at edge locations
    • Reduce latency for global users
    # Example: Kubernetes deployment with scaling
apiVersion: apps/v1
kind: Deployment
metadata:
  name: dify-api
spec:
  replicas: 3  # Horizontal scaling
  template:
    spec:
      containers:
      - name: api
        image: langgenius/dify-api:1.14.2
        resources:
          requests:
            cpu: "1"
            memory: "2Gi"
          limits:
            cpu: "2"
            memory: "4Gi"
---
# Separate worker deployment for generation queue
apiVersion: apps/v1
kind: Deployment
metadata:
  name: dify-worker-generation
spec:
  replicas: 5
  template:
    spec:
      containers:
      - name: worker
        image: langgenius/dify-api:1.14.2
        command: ["celery"]
        args: ["-A", "celery_entrypoint", "worker", "-Q", "generation", "-P", "gevent", "-c", "4"]
  18. Step 18

    Troubleshooting common issues

    Solutions to common deployment and operational issues:

    Issue: Services fail to start

    • Check Docker logs: docker compose logs [service]
    • Verify .env configuration is complete
    • Ensure ports 80, 443, 5001, 6379, 5432 are not in use
    • Check file permissions on volumes

    Issue: Database migration fails

    • Ensure database is accessible and credentials are correct
    • Run migrations manually: docker compose exec api flask db upgrade
    • Check migration logs for specific errors

    Issue: Vector search not working

    • Verify vector database is running and accessible
    • Check VECTOR_STORE environment variable
    • Ensure documents are properly indexed
    • Check vector database logs

    Issue: LLM provider errors

    • Verify API keys are correct and active
    • Check rate limits and quotas
    • Test provider connectivity from container
    • Review model availability in selected region

    Issue: Performance degradation

    • Monitor database query performance
    • Check Celery queue backlogs
    • Review Redis memory usage
    • Analyze slow API endpoints in logs
    • Scale workers or API instances as needed
    # Debug services
docker compose logs -f api       # Follow API logs
docker compose logs -f worker    # Follow worker logs

# Check service health
docker compose ps
docker compose exec api flask --help

# Test database connection
docker compose exec db_postgres psql -U postgres -d dify -c "SELECT version();"

# Test Redis connection
docker compose exec redis redis-cli ping

# Check Celery worker status
docker compose exec worker celery -A celery_entrypoint inspect active

# View resource usage
docker stats

# Restart specific service
docker compose restart api
  19. Step 19

    Upgrading Dify

    Safely upgrade to newer versions of Dify:

    Preparation:

    1. Review release notes for breaking changes
    2. Backup database and configuration files
    3. Test upgrade in staging environment first
    4. Schedule maintenance window

    Upgrade steps for Docker deployment:

    1. Pull new images: docker compose pull
    2. Stop services: docker compose down
    3. Run database migrations: docker compose run --rm api flask db upgrade
    4. Start services: docker compose up -d
    5. Verify functionality and check logs

    For source deployments:

    1. Pull latest code: git pull origin main
    2. Update backend dependencies: uv sync
    3. Update frontend dependencies: pnpm install
    4. Run migrations: flask db upgrade
    5. Rebuild and restart services

    Rollback plan:

    • Keep previous version images tagged
    • Maintain database backups before upgrade
    • Document rollback procedure
    • Test rollback process
    # Backup before upgrade
docker compose exec db_postgres pg_dump -U postgres dify > backup_pre_upgrade.sql

# Upgrade via Docker
cd dify/docker
docker compose pull
docker compose down
docker compose run --rm api flask db upgrade
docker compose up -d

# Check version
docker compose exec api cat /app/api/version.txt

# Monitor logs after upgrade
docker compose logs -f --tail=100

# Rollback if needed (use previous image tag)
docker compose down
# Edit docker-compose.yaml to use previous version tag
docker compose up -d
  20. Step 20

    Community and resources

    Official resources:

    • Website: https://dify.ai
    • Documentation: https://docs.dify.ai
    • GitHub: https://github.com/langgenius/dify (142,000+ stars)
    • Cloud platform: https://cloud.dify.ai (200 free GPT-4 calls)

    Community:

    • Discord: https://discord.gg/FngNHpbcY7 (primary community hub)
    • Reddit: https://reddit.com/r/difyai
    • Twitter/X: @dify_ai
    • LinkedIn: https://www.linkedin.com/company/langgenius/

    Enterprise:

    • Business inquiries: business@dify.ai
    • AWS Marketplace: Dify Premium AMI available
    • Premium editions: Enterprise features, custom branding, SLA support

    Contributing:

    • Contribution guide: https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md
    • Translations needed in multiple languages
    • Community Helm charts and deployment tools
    Primary Resources:
├── Docs: https://docs.dify.ai
├── GitHub: https://github.com/langgenius/dify
├── Discord: https://discord.gg/FngNHpbcY7
├── Cloud: https://cloud.dify.ai
└── Docker Hub: https://hub.docker.com/u/langgenius

Deployment Tools:
├── Official Docker Compose
├── Community Helm Charts (Douban, BorisPolonsky, magicsong)
├── Terraform (Azure, GCP)
├── AWS CDK (EKS, ECS)
└── Alibaba Cloud Computing Nest

Feature requests

Sign in to suggest features or vote on existing ones.

No feature requests yet.

Discussion

0 people marked this as worked·Sign in to mark your own.

Sign in to join the discussion.

No comments yet.