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), and6379(Redis) available
Step-by-Step Setup
-
Clone the repository and navigate to the directory:
git clone https://github.com/langgenius/dify.git cd dify -
Copy the example environment file and edit it:
cp .env.example .env nano .env # or use your preferred editorKey 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 -
Start the services:
docker-compose up -dExpected output:
Creating dify-redis ... done Creating dify-db ... done Creating dify-api ... done Creating dify-worker ... done Creating dify-web ... done -
Verify the containers are running:
docker-compose psExpected 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 -
Access the Dify dashboard:
- Open
http://localhost:3000in your browser. - Register an admin account (this will be the first user).
- Open
Common Errors & Fixes
-
Error:
Port 3000 already in useFix: Stop the conflicting service or change the port indocker-compose.yml(updateportsfordify-web). -
Error:
PostgreSQL connection refusedFix: EnsureDB_HOST=dbin.env(Docker internal networking). If using an external DB, setDB_HOSTto the correct IP/hostname. -
Error:
Redis connection failedFix: VerifyREDIS_HOST=redisin.env. If Redis is external, updateREDIS_HOSTand ensure the port (6379) is open.
## 2. Creating Your First Chatbot
Step 1: Navigate to the Studio
- Log in to Dify at
http://localhost:3000. - Click "Studio" in the left sidebar.
- Click "Create Application" and select "Chatbot".
Step 2: Configure the Chatbot
- Name:
My First Chatbot - Description:
A simple Q&A bot for testing Dify. - Model Provider: Select
OpenAI(or another provider you’ve configured — see Section 6).- For local testing, use
Ollamawith a model likellama3(requires Ollama running locally).
- For local testing, use
- Prompt Template:
You are a helpful assistant. Answer the user's question concisely. User question: {{query}} - Click "Save" to create the chatbot.
Step 3: Test the Chatbot
- Click the "Debug" tab in the chatbot editor.
- Type a test question (e.g.,
What is Dify?). - Verify the response matches your prompt template.
Step 4: Publish the Chatbot
- Click the "Publish" button in the top-right corner.
- Select "Publish to Production".
- Your chatbot is now live at:
(Replace
http://localhost:3000/chatbot/{app-id}{app-id}with your chatbot’s ID from the URL.)
## 3. Knowledge Base and RAG Setup
Step 1: Create a Knowledge Base
- In the Dify dashboard, click "Knowledge" in the left sidebar.
- Click "Create Knowledge Base".
- Name:
Product Documentation - Description:
Internal product docs for RAG. - Embedding Model: Select
text-embedding-ada-002(OpenAI) orbge-small-en(local). - Click "Save".
Step 2: Upload Documents
- Click the "Documents" tab in your knowledge base.
- Click "Upload" and select a file (supports PDF, TXT, Markdown, DOCX, CSV).
- Example: Upload a PDF of your product documentation.
- Wait for the document to process (status will change from
QueuedtoIndexed).
Step 3: Connect the Knowledge Base to Your Chatbot
- Open your chatbot in the Studio.
- Click the "Context" tab in the left sidebar.
- Click "Add Knowledge Base" and select
Product Documentation. - 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}} - Click "Save" and test the chatbot with a question about your documentation.
Step 4: Configure Advanced RAG Settings
- In the Context tab, click the gear icon (⚙️) next to your knowledge base.
- Adjust the following settings:
- Top K:
3(number of chunks to retrieve) - Score Threshold:
0.5(minimum relevance score) - Retrieval Mode:
Single(orMultiplefor multi-document queries)
- Top K:
- Click "Save".
## 4. Workflow Builder
Step 1: Create a Workflow
- In the Dify dashboard, click "Studio" > "Create Application" > "Workflow".
- Name:
Customer Support Triage - Description:
Route customer queries to the right team.
Step 2: Build the Workflow
- Drag a "Start" node onto the canvas.
- 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:
- Model:
- 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.
- Action: Connect to a "Reply" node with the message:
- Condition 2:
{{llm_output}} contains "Technical Support"- Action: Connect to a "Reply" node with the message:
A technical support agent will contact you shortly.
- Action: Connect to a "Reply" node with the message:
- Default Condition: Connect to a "Reply" node with the message:
Thanks for your message! We'll get back to you soon.
- Condition 1:
- Click "Save".
Step 3: Test the Workflow
- Click the "Debug" tab.
- Enter a test query (e.g.,
I have a question about my invoice). - Verify the workflow routes the query correctly.
Step 4: Publish the Workflow
- Click "Publish" > "Publish to Production".
- The workflow is now available as an API (see Section 5).
## 5. API Access and Embedding
Step 1: Get Your API Key
- In the Dify dashboard, click your profile icon > "API Keys".
- Click "Create New Key".
- Name:
My App Key - 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
- In the Dify dashboard, click "Settings" > "Model Providers".
- Click "Add Provider" and select OpenAI.
- Enter your OpenAI API key (get it from OpenAI Platform).
- Click "Save".
Step 2: Add a Local Model (Ollama)
- Install Ollama locally:
curl -fsSL https://ollama.com/install.sh | sh ollama pull llama3 - In Dify, go to "Settings" > "Model Providers".
- Click "Add Provider" and select Ollama.
- Base URL:
http://host.docker.internal:11434(usehost.docker.internalto access the host machine from Docker). - Click "Save".
Step 3: Add Anthropic (Claude)
- Get an Anthropic API key from Anthropic Console.
- In Dify, go to "Settings" > "Model Providers".
- Click "Add Provider" and select Anthropic.
- Enter your API key and click "Save".
Step 4: Use a Custom Model
- In the Model Providers settings, click "Add Provider" > "Custom".
- Name:
My Custom Model - Base URL:
https://api.your-model-provider.com/v1 - API Key:
your-api-key - Models: Add your model(s) with their
nameandcontext_length. - Click "Save".
## 7. Production Deployment
Option 1: Kubernetes (Helm)
- Add the Dify Helm repository:
helm repo add dify https://dify-ai.github.io/helm-charts helm repo update
