How to Set Up Dify: A Practical Guide

TL;DR

• Self-host Dify in 5 minutes with Docker Compose (docker-compose up -d)
• Build your first chatbot in the visual editor — no code required
• Add RAG by uploading documents to a knowledge base (supports PDF, TXT, Markdown)
• Extend with workflows, APIs, or custom model providers (OpenAI, Ollama, etc.)
• Deploy to production with Kubernetes or cloud providers

## 1. Self-Hosting with Docker Compose

Prerequisites

• Docker Engine ≥ 24.0.0 and Docker Compose ≥ 2.23.0 Docker Install Guide
• 4GB+ RAM, 2 vCPUs (8GB+ RAM recommended for production)
• Ports 3000 (frontend), 5001 (API), and 6379 (Redis) available

Step-by-Step Setup

1. Clone the repository and navigate to the directory:

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

   Copy

2. Copy the example environment file and edit it:

   cp .env.example .env
   nano .env  # or use your preferred editor
   

   Copy

   Key variables to configure:

   # Required for self-hosting
   CONSOLE_API_URL=http://localhost:5001
   APP_API_URL=http://localhost:5001
   SECRET_KEY=your-random-secret-key-here  # Generate with `openssl rand -hex 32`
   
   # Optional: Configure mail (for password resets)
   MAIL_DEFAULT_SENDER=no[email protected]
   SMTP_SERVER=smtp.yourprovider.com
   SMTP_PORT=587
   SMTP_USERNAME[email protected]
   SMTP_PASSWORD=your-smtp-password
   

   Copy

3. Start the services:

   docker-compose up -d
   

   Copy

   Expected output:

   Creating dify-redis    ... done
   Creating dify-db       ... done
   Creating dify-api      ... done
   Creating dify-worker   ... done
   Creating dify-web      ... done
   

   Copy

4. Verify the containers are running:

   docker-compose ps
   

   Copy

   Expected output:

   Name                Command               State           Ports
   -----------------------------------------------------------------
   dify-api      /bin/sh -c gunicorn ...   Up      0.0.0.0:5001->5001/tcp
   dify-db       docker-entrypoint.sh ...  Up      5432/tcp
   dify-redis    docker-entrypoint.sh ...  Up      6379/tcp
   dify-web      /docker-entrypoint.sh     Up      0.0.0.0:3000->3000/tcp
   dify-worker   /bin/sh -c celery -A ...  Up
   

   Copy

5. Access the Dify dashboard:

   • Open http://localhost:3000 in your browser.
   • Register an admin account (this will be the first user).

Common Errors & Fixes

• Error: Port 3000 already in use Fix: Stop the conflicting service or change the port in docker-compose.yml (update ports for dify-web).

• Error: PostgreSQL connection refused Fix: Ensure DB_HOST=db in .env (Docker internal networking). If using an external DB, set DB_HOST to the correct IP/hostname.

• Error: Redis connection failed Fix: Verify REDIS_HOST=redis in .env. If Redis is external, update REDIS_HOST and ensure the port (6379) is open.

## 2. Creating Your First Chatbot

Step 1: Navigate to the Studio

1. Log in to Dify at http://localhost:3000.
2. Click "Studio" in the left sidebar.
3. Click "Create Application" and select "Chatbot".

Step 2: Configure the Chatbot

1. Name: My First Chatbot
2. Description: A simple Q&A bot for testing Dify.
3. Model Provider: Select OpenAI (or another provider you’ve configured — see Section 6).
   • For local testing, use Ollama with a model like llama3 (requires Ollama running locally).
4. Prompt Template:

   You are a helpful assistant. Answer the user's question concisely.
   
   User question: {{query}}
   

   Copy
5. Click "Save" to create the chatbot.

Step 3: Test the Chatbot

1. Click the "Debug" tab in the chatbot editor.
2. Type a test question (e.g., What is Dify?).
3. Verify the response matches your prompt template.

Step 4: Publish the Chatbot

1. Click the "Publish" button in the top-right corner.
2. Select "Publish to Production".
3. Your chatbot is now live at:

   http://localhost:3000/chatbot/{app-id}
   

   Copy
   (Replace {app-id} with your chatbot’s ID from the URL.)

## 3. Knowledge Base and RAG Setup

Step 1: Create a Knowledge Base

1. In the Dify dashboard, click "Knowledge" in the left sidebar.
2. Click "Create Knowledge Base".
3. Name: Product Documentation
4. Description: Internal product docs for RAG.
5. Embedding Model: Select text-embedding-ada-002 (OpenAI) or bge-small-en (local).
6. Click "Save".

Step 2: Upload Documents

1. Click the "Documents" tab in your knowledge base.
2. Click "Upload" and select a file (supports PDF, TXT, Markdown, DOCX, CSV).
   • Example: Upload a PDF of your product documentation.
3. Wait for the document to process (status will change from Queued to Indexed).

Step 3: Connect the Knowledge Base to Your Chatbot

1. Open your chatbot in the Studio.
2. Click the "Context" tab in the left sidebar.
3. Click "Add Knowledge Base" and select Product Documentation.
4. Update the prompt template to include the knowledge base:

   You are a helpful assistant. Use the following context to answer the user's question:
   
   Context:
   {{knowledge}}
   
   User question: {{query}}
   

   Copy
5. Click "Save" and test the chatbot with a question about your documentation.

Step 4: Configure Advanced RAG Settings

1. In the Context tab, click the gear icon (⚙️) next to your knowledge base.
2. Adjust the following settings:
   • Top K: 3 (number of chunks to retrieve)
   • Score Threshold: 0.5 (minimum relevance score)
   • Retrieval Mode: Single (or Multiple for multi-document queries)
3. Click "Save".

## 4. Workflow Builder

Step 1: Create a Workflow

1. In the Dify dashboard, click "Studio" > "Create Application" > "Workflow".
2. Name: Customer Support Triage
3. Description: Route customer queries to the right team.

Step 2: Build the Workflow

1. Drag a "Start" node onto the canvas.
2. Drag an "LLM" node and connect it to the Start node.
   • Model: gpt-4o (or your preferred model)
   • Prompt:

     Classify the user's query into one of these categories:
     - Billing
     - Technical Support
     - General Inquiry
     
     Query: {{query}}
     Category:
     

     Copy
3. Drag a "Condition" node and connect it to the LLM node.
   • Condition 1: {{llm_output}} contains "Billing"
     • Action: Connect to a "Reply" node with the message:

       Your billing request has been forwarded to the finance team.
       

       Copy
   • Condition 2: {{llm_output}} contains "Technical Support"
     • Action: Connect to a "Reply" node with the message:

       A technical support agent will contact you shortly.
       

       Copy
   • Default Condition: Connect to a "Reply" node with the message:

     Thanks for your message! We'll get back to you soon.
     

     Copy
4. Click "Save".

Step 3: Test the Workflow

1. Click the "Debug" tab.
2. Enter a test query (e.g., I have a question about my invoice).
3. Verify the workflow routes the query correctly.

Step 4: Publish the Workflow

1. Click "Publish" > "Publish to Production".
2. The workflow is now available as an API (see Section 5).

## 5. API Access and Embedding

Step 1: Get Your API Key

1. In the Dify dashboard, click your profile icon > "API Keys".
2. Click "Create New Key".
3. Name: My App Key
4. Copy the generated API key (you won’t see it again).

Step 2: Call the Chatbot API

Use curl to interact with your chatbot:

curl --location 'http://localhost:5001/v1/chat-messages' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
  "inputs": {},
  "query": "What is Dify?",
  "response_mode": "blocking",
  "conversation_id": "",
  "user": "test-user"
}'

Expected output:

{
  "event": "message",
  "message_id": "abc123",
  "conversation_id": "xyz456",
  "answer": "Dify is an open-source LLM app development platform..."
}

Step 3: Embed the Chatbot in a Web App

Use the Dify JavaScript SDK to embed your chatbot:

<!DOCTYPE html>
<html>
<head>
  <title>Dify Chatbot Embed</title>
  <script src="https://cdn.jsdelivr.net/npm/@dify/[email protected]/dist/dify.umd.min.js"></script>
</head>
<body>
  <div id="dify-chatbot" style="width: 400px; height: 600px;"></div>
  <script>
    const chatbot = new DifyChatbot({
      el: '#dify-chatbot',
      appId: '{YOUR_APP_ID}',  // Get this from the chatbot URL
      apiHost: 'http://localhost:5001',
      apiKey: '{YOUR_API_KEY}',
      user: 'web-user'
    });
  </script>
</body>
</html>

Note: Replace {YOUR_APP_ID} and {YOUR_API_KEY} with your values.

## 6. Model Provider Configuration

Step 1: Add OpenAI

1. In the Dify dashboard, click "Settings" > "Model Providers".
2. Click "Add Provider" and select OpenAI.
3. Enter your OpenAI API key (get it from OpenAI Platform).
4. Click "Save".

Step 2: Add a Local Model (Ollama)

1. Install Ollama locally:

   curl -fsSL https://ollama.com/install.sh | sh
   ollama pull llama3
   

   Copy
2. In Dify, go to "Settings" > "Model Providers".
3. Click "Add Provider" and select Ollama.
4. Base URL: http://host.docker.internal:11434 (use host.docker.internal to access the host machine from Docker).
5. Click "Save".

Step 3: Add Anthropic (Claude)

1. Get an Anthropic API key from Anthropic Console.
2. In Dify, go to "Settings" > "Model Providers".
3. Click "Add Provider" and select Anthropic.
4. Enter your API key and click "Save".

Step 4: Use a Custom Model

1. In the Model Providers settings, click "Add Provider" > "Custom".
2. Name: My Custom Model
3. Base URL: https://api.your-model-provider.com/v1
4. API Key: your-api-key
5. Models: Add your model(s) with their name and context_length.
6. Click "Save".

## 7. Production Deployment

Option 1: Kubernetes (Helm)

1. Add the Dify Helm repository:

   helm repo add dify https://dify-ai.github.io/helm-charts
   helm repo update
   

   Copy