Deploying Dify

Introduction

Dify is an open-source LLM application development platform that combines AI workflow orchestration, model management, and RAG pipeline capabilities. It provides an intuitive interface for building AI applications, managing prompts, and deploying production-ready LLM services with features like model fine-tuning, dataset management, and comprehensive observability.

This guide explains how to deploy Dify on Klutch.sh using a Dockerfile, covering installation steps, environment configuration, persistent storage setup, and production best practices. Dify on Klutch.sh enables you to run scalable AI applications with managed infrastructure, automatic deployments from GitHub, and secure environment handling.

Prerequisites

A Klutch.sh account (sign up here)
A GitHub account and repository for your Dify deployment
Basic knowledge of Docker and containerized applications
PostgreSQL database (for production deployments)
Redis instance (for caching and session management)
OpenAI API key or compatible LLM provider credentials

Getting Started: Understanding Dify Architecture

Dify consists of several components:

API Service: Backend service that handles model orchestration and business logic
Web Application: Frontend interface for workflow design and management
Worker: Background task processor for async operations
Database: PostgreSQL for storing application data, workflows, and datasets
Redis: For caching, session storage, and task queuing
Object Storage: For file uploads and dataset storage (S3-compatible)

For a production deployment, you’ll need to set up these components. This guide focuses on deploying the main Dify API and web services.

Installation Steps

Step 1: Create Your Dify Repository

Create a new repository on GitHub or fork the official Dify repository.

Clone the repository to your local machine:

git clone https://github.com/yourusername/dify.git
cd dify

Create a Dockerfile in the root directory (see sample below).

Step 2: Sample Dockerfile for Dify API

Create a Dockerfile in your repository root with the following content:

FROM python:3.10-slim

# Set working directory
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    libpq-dev \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements file
COPY api/requirements.txt ./

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY api/ ./

# Create directories for persistent data
RUN mkdir -p /app/storage

# Expose port
EXPOSE 5001

# Health check (adjust endpoint based on your Dify configuration)
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:5001/ || exit 1

# Start the application
CMD ["gunicorn", \
     "--bind", "0.0.0.0:5001", \
     "--workers", "4", \
     "--worker-class", "gevent", \
     "--timeout", "360", \
     "--log-level", "info", \
     "app:app"]

Step 3: Sample Code for Basic Configuration

Create a .env.example file to document required environment variables:

# Application Settings
MODE=production
LOG_LEVEL=INFO
SECRET_KEY=your-secret-key-change-this

# Database Configuration
DB_USERNAME=postgres
DB_PASSWORD=your-postgres-password
DB_HOST=your-postgres-host
DB_PORT=5432
DB_DATABASE=dify

# Redis Configuration
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
REDIS_DB=0

# Storage Configuration (S3-compatible)
STORAGE_TYPE=s3
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET_NAME=dify-storage
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_REGION=us-east-1

# LLM Provider Configuration
OPENAI_API_KEY=your-openai-api-key

# Application URL (replace with your actual app URL)
# Note: For single-instance deployment, both API and Web use the same URL
APP_API_URL=https://your-app-name.klutch.sh
APP_WEB_URL=https://your-app-name.klutch.sh

# Vector Database (Optional - for RAG)
VECTOR_STORE=weaviate
WEAVIATE_ENDPOINT=http://weaviate:8080
WEAVIATE_API_KEY=your-weaviate-key

Step 4: Push to GitHub

git add Dockerfile .env.example
git commit -m "Add Dify Dockerfile and configuration"
git push origin main

Deploying Dify on Klutch.sh

Klutch.sh automatically detects the Dockerfile in your repository root and uses it to build and deploy your application.

Log in to Klutch.sh

Navigate to klutch.sh/app and sign in to your account.
Create a New Project

Click “Create Project” and give your project a descriptive name (e.g., “Dify AI Platform”).
Create a New App

Within your project, click “Create App” and configure:
- Repository: Select your Dify GitHub repository
- Branch: Choose your deployment branch (e.g., main)
- Traffic Type: Select HTTP
- Internal Port: Set to 5001 (Dify API default port)
- Region: Choose your preferred deployment region
- Compute: Select appropriate resources (minimum 2GB RAM recommended)
- Instances: Start with 1, scale as needed
Configure Environment Variables

Add the following required environment variables in the Klutch.sh app settings:
- MODE=production
- SECRET_KEY=<generate-a-secure-random-key>
- DB_USERNAME=<your-postgres-username>
- DB_PASSWORD=<your-postgres-password>
- DB_HOST=<your-postgres-host>
- DB_PORT=5432
- DB_DATABASE=dify
- REDIS_HOST=<your-redis-host>
- REDIS_PORT=6379
- REDIS_PASSWORD=<your-redis-password>
- OPENAI_API_KEY=<your-openai-api-key>
- APP_API_URL=https://your-app-name.klutch.sh
- APP_WEB_URL=https://your-app-name.klutch.sh
- STORAGE_TYPE=s3
- S3_ENDPOINT=<your-s3-endpoint>
- S3_BUCKET_NAME=<your-bucket-name>
- S3_ACCESS_KEY=<your-s3-access-key>
- S3_SECRET_KEY=<your-s3-secret-key>
Attach Persistent Volumes

For persistent storage of uploaded files and datasets:
- Navigate to the “Volumes” section in your app settings
- Click “Add Volume”
- Mount Path: /app/storage
- Size: Choose based on your needs (start with 10GB, scale up as needed)
The volume will be automatically created and attached to your container.
Deploy the Application

Click “Create” to start the deployment. Klutch.sh will:
- Detect your Dockerfile automatically
- Build the Docker image
- Deploy the container with your configuration
- Assign a public URL like example-app.klutch.sh

Setting Up the Database

Before your Dify application can function properly, you need to initialize the database schema.

Option 1: Using a Separate Migration Job

You can run database migrations as a one-time job:

Create a separate app in Klutch.sh with the same database credentials
Use this Dockerfile for migrations:

FROM python:3.10-slim

WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev \
    curl \
    && rm -rf /var/lib/apt/lists/*

COPY api/requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY api/ ./

CMD ["flask", "db", "upgrade"]

Option 2: Include in Startup Script

Alternatively, modify your main Dockerfile’s CMD to run migrations on startup:

CMD ["sh", "-c", "flask db upgrade && gunicorn --bind 0.0.0.0:5001 --workers 4 --worker-class gevent app:app"]

Configuring External Dependencies

PostgreSQL Database

Dify requires PostgreSQL 12 or higher. You can either:

Use a managed PostgreSQL service (AWS RDS, DigitalOcean, etc.)
Deploy PostgreSQL on Klutch.sh as a separate app
Use Supabase for a fully managed solution

Redis Instance

Redis is used for caching and task queuing. Options include:

Managed Redis service (AWS ElastiCache, Redis Cloud, etc.)
Deploy Redis on Klutch.sh as a separate app
Use Upstash for serverless Redis

Object Storage

For file uploads and dataset storage, you’ll need S3-compatible storage:

AWS S3
DigitalOcean Spaces
Cloudflare R2
MinIO (self-hosted)

Environment Variables Reference

Core Application Settings

Variable	Required	Description	Example
`MODE`	Yes	Application mode	`production`
`LOG_LEVEL`	No	Logging level	`INFO`
`SECRET_KEY`	Yes	Application secret key	`your-secret-key`
`APP_API_URL`	Yes	Public API URL	`https://your-app-name.klutch.sh`

Database Configuration

Variable	Required	Description	Example
`DB_USERNAME`	Yes	PostgreSQL username	`postgres`
`DB_PASSWORD`	Yes	PostgreSQL password	`your-password`
`DB_HOST`	Yes	PostgreSQL host	`db.example.com`
`DB_PORT`	Yes	PostgreSQL port	`5432`
`DB_DATABASE`	Yes	Database name	`dify`

Redis Configuration

Variable	Required	Description	Example
`REDIS_HOST`	Yes	Redis host	`redis.example.com`
`REDIS_PORT`	Yes	Redis port	`6379`
`REDIS_PASSWORD`	No	Redis password	`your-password`
`REDIS_DB`	No	Redis database number	`0`

LLM Provider Configuration

Variable	Required	Description	Example
`OPENAI_API_KEY`	No*	OpenAI API key	`sk-...`
`ANTHROPIC_API_KEY`	No*	Anthropic API key	`sk-ant-...`
`AZURE_OPENAI_API_KEY`	No*	Azure OpenAI key	`your-key`

*At least one LLM provider key is required

Customizing Build and Runtime with Nixpacks

While Klutch.sh automatically detects your Dockerfile, you can customize the build process using environment variables if needed:

BUILD_COMMAND: Override the default build command
- Example: BUILD_COMMAND=pip install -r requirements.txt && python setup.py build
START_COMMAND: Override the default start command
- Example: START_COMMAND=gunicorn --bind 0.0.0.0:5001 app:app
PYTHON_VERSION: Specify a Python version
- Example: PYTHON_VERSION=3.10

Production Best Practices

Security

Never commit secrets: Use Klutch.sh environment variables for all sensitive data
Use strong SECRET_KEY: Generate a cryptographically secure random string
Enable HTTPS: Klutch.sh provides automatic HTTPS for all deployments
Restrict API access: Implement authentication and rate limiting
Regular updates: Keep dependencies updated for security patches

Performance

Use connection pooling: Configure PostgreSQL connection pooling
Enable Redis caching: Properly configure Redis for optimal performance
Monitor resources: Use Klutch.sh monitoring to track CPU, memory, and disk usage
Scale horizontally: Add more instances during high traffic periods
Optimize Docker image: Use multi-stage builds to reduce image size

Reliability

Health checks: Implement proper health check endpoints
Graceful shutdown: Handle SIGTERM signals for clean shutdowns
Database backups: Set up regular PostgreSQL backups
Volume backups: Create snapshots of persistent volumes
Disaster recovery: Document and test recovery procedures

Monitoring and Logging

Structured logging: Use JSON logging for easier parsing
Log aggregation: Configure log forwarding if needed
Application metrics: Monitor request rates, latency, and error rates
Alert configuration: Set up alerts for critical issues
Performance profiling: Use APM tools for performance insights

Scaling Your Dify Deployment

Vertical Scaling

Increase resources for your existing instances:

Navigate to your app settings in Klutch.sh
Adjust compute resources (CPU/Memory)
Save changes and redeploy

Horizontal Scaling

Add more instances to handle increased load:

In your app settings, increase the instance count
Ensure your database can handle multiple connections
Configure load balancing (handled automatically by Klutch.sh)

Database Scaling

For high-traffic deployments:

Use PostgreSQL read replicas for read-heavy workloads
Consider connection pooling with PgBouncer
Optimize database queries and add indexes

Troubleshooting

Application Won’t Start

Check logs: View application logs in Klutch.sh dashboard
Verify environment variables: Ensure all required variables are set
Database connectivity: Test PostgreSQL connection from your app
Port configuration: Confirm internal port matches Dockerfile EXPOSE directive

Database Connection Errors

Verify credentials: Double-check database username, password, and host
Network access: Ensure database allows connections from Klutch.sh
Connection string: Verify the database URL format
SSL requirements: Check if your database requires SSL connections

Storage Issues

Volume permissions: Ensure the container user has write access
Disk space: Monitor volume usage and increase size if needed
S3 credentials: Verify S3 access keys and bucket permissions
Network egress: Ensure container can reach external storage endpoints

Performance Problems

Resource limits: Check if app is hitting CPU/memory limits
Database performance: Review slow query logs
Redis connectivity: Verify Redis is responding quickly
Network latency: Check latency between services

Advanced Configuration

Using GPU for Model Inference

For running models locally with GPU acceleration:

Update your Dockerfile to use a CUDA base image:

FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04

# Install Python
RUN apt-get update && apt-get install -y python3.10 python3-pip

# Continue with standard setup...

Select GPU-enabled compute in Klutch.sh app settings
Install CUDA-compatible packages (PyTorch, TensorFlow, etc.)

Custom Model Providers

To add custom LLM providers:

Configure provider credentials in environment variables
Update Dify configuration to register the new provider
Restart the application to apply changes

Webhook Integration

Configure webhooks for external service integration:

Set WEBHOOK_URL environment variable
Configure authentication tokens as needed
Test webhook delivery with sample payloads

Sample Production Dockerfile

For a complete production-ready setup:

# Multi-stage build for smaller final image
FROM python:3.10-slim as builder

WORKDIR /build

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

COPY api/requirements.txt ./
RUN pip install --no-cache-dir --user -r requirements.txt

# Final stage
FROM python:3.10-slim

WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq5 \
    curl \
    && rm -rf /var/lib/apt/lists/* \
    && useradd -m -u 1000 dify

# Copy Python packages from builder
COPY --from=builder /root/.local /root/.local
ENV PATH=/root/.local/bin:$PATH

# Copy application code
COPY --chown=dify:dify api/ ./

# Create necessary directories
RUN mkdir -p /app/storage && chown -R dify:dify /app

# Switch to non-root user
USER dify

# Expose port
EXPOSE 5001

# Health check (adjust endpoint based on your Dify configuration)
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:5001/ || exit 1

# Start application
CMD ["gunicorn", \
     "--bind", "0.0.0.0:5001", \
     "--workers", "4", \
     "--worker-class", "gevent", \
     "--timeout", "360", \
     "--log-level", "info", \
     "--access-logfile", "-", \
     "--error-logfile", "-", \
     "app:app"]

Resources

Deploying Dify on Klutch.sh provides you with a powerful, scalable platform for building and deploying AI applications. With automatic Dockerfile detection, managed infrastructure, and seamless GitHub integration, you can focus on building great AI experiences while Klutch.sh handles the deployment complexity.