Complete Guide to Deploying and Using Dify Locally With Docker

Building production-ready AI applications no longer requires a team of machine learning engineers. Dify — whose name comes from "Do It For You" — is an open-source platform that lets you visually orchestrate AI models, connect data sources, and define processing pipelines on a drag-and-drop canvas. Whether you want a customer service chatbot, an internal knowledge assistant, or a multi-step research agent, Dify provides the building blocks to go from idea to working software in minutes rather than weeks.

This tutorial walks you through everything you need to know to get Dify running on your own machine. We will cover system requirements, a step-by-step Docker Compose deployment, post-install configuration, your first application build, and advanced features like knowledge bases, workflows, and MCP tool integration. By the end, you will have a fully functional local AI application platform ready for real projects.

Understanding Dify's Architecture

Before typing any commands, it helps to understand what runs under the hood. Dify is not a single monolithic application. It is a collection of cooperating services, each with a distinct responsibility.

Core Services

When you deploy Dify with Docker Compose, five core services start automatically:

• API — The backend REST API server (Flask-based) that handles all business logic, authentication, and orchestration.
• Worker — A Celery asynchronous task worker that processes long-running jobs such as document embedding, batch generation, and background workflows.
• Worker Beat — The Celery beat scheduler that triggers periodic tasks like cleaning expired sessions or scheduled indexing.
• Web — The Next.js frontend application that serves the visual studio interface you interact with in the browser.
• Plugin Daemon — A dedicated service that manages the lifecycle and execution of Dify plugins, including custom tools and model providers.

Dependency Components

In addition to the core services, six infrastructure components are launched:

• PostgreSQL (db_postgres) — The primary relational database storing users, applications, conversations, and metadata.
• Redis — An in-memory store used for caching, session management, and as a Celery message broker.
• Weaviate — The default vector database for storing and检索 embeddings that power Retrieval-Augmented Generation (RAG).
• Nginx — A reverse proxy that routes external HTTP/HTTPS traffic to the appropriate internal services.
• SSRF Proxy — A Squid-based proxy that guards against Server-Side Request Forgery attacks when Dify fetches external URLs.
• Sandbox — An isolated execution environment for running user-submitted code safely (used in code nodes within workflows).

Understanding this architecture is crucial when troubleshooting. If your knowledge base indexing stalls, for example, you should check the Worker logs, not the API logs.

System Requirements and Prerequisites

Hardware Requirements

Dify is relatively lightweight for a development environment, but it does run over a dozen containers simultaneously. Here are the minimum and recommended specifications:

• CPU: Minimum 2 cores. Recommended 4+ cores for smooth operation, especially when running local models through Ollama alongside Dify.
• RAM: Minimum 4 GiB. Recommended 8 GiB or more. The vector database, Redis, and multiple application containers together consume significant memory.
• Disk: At least 20 GiB of free space. Docker images, vector data, and uploaded documents accumulate over time.

Software Requirements by Operating System

macOS (10.14 or later)

Install Docker Desktop for Mac, which includes Docker Compose. Ensure the Docker virtual machine is configured with at least 2 virtual CPUs and 8 GiB of memory. You can adjust these settings in Docker Desktop → Settings → Resources.

Linux (Ubuntu, Debian, CentOS, etc.)

You need Docker Engine 19.03 or later and Docker Compose 2.24.0 or later. Most modern Linux distributions can install these through their package managers. Verify your versions:

# Check Docker version

docker --version

# Should output: Docker version 24.x.x or higher

# Check Docker Compose version (note the V2 syntax)

docker compose version

# Should output: Docker Compose version v2.24.0 or higher

Windows (with WSL 2)

Install Docker Desktop for Windows with the WSL 2 backend enabled. An important caveat: store your Dify source code and any bind-mounted data inside the Linux file system (e.g., under your WSL home directory), not on the Windows file system. Cross-filesystem bind mounts suffer from severe performance penalties and can cause file-watching issues.

LLM API Key

While Dify itself is free and open-source, you need access to at least one large language model. Options include:

• Cloud providers: OpenAI (GPT-4o, GPT-4o-mini), Anthropic (Claude), Google (Gemini), DeepSeek, Zhipu AI (GLM), and many others.
• Local models: Ollama running on the same machine or a nearby server. This is ideal for air-gapped environments or when you want zero per-token costs.

Have your API key ready before proceeding to the configuration section.

Step-by-Step Deployment With Docker Compose

This is the recommended and most straightforward deployment method. Follow these steps carefully.

Step 1: Clone the Repository

Clone the Dify source code at the latest stable release:

# Clone the latest stable release automatically

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git

# If you don't have jq installed, manually check the latest release tag at:

# https://github.com/langgenius/dify/releases

# Then clone with the specific tag, for example:

# git clone --branch 1.0.0 https://github.com/langgenius/dify.git

Note: If you are behind a corporate firewall or in a region with unreliable GitHub access, consider using a mirror or proxy. You can also download the release archive directly from the GitHub releases page.

Step 2: Prepare the Environment File

Navigate to the Docker directory and create your environment configuration:

cd dify/docker

# Copy the example environment file

cp .env.example .env

The .env file controls every aspect of your deployment. We will customize it in the next section, but the defaults are sufficient to get started.

Step 3: Launch All Services

Start the containers in detached mode:

docker compose up -d

This command downloads the necessary images and starts all services. The first run will take several minutes depending on your internet speed. You should see output similar to:

[+] Running 13/13

 ✔ Network docker_ssrf_proxy_network  Created    10.0s

 ✔ Network docker_default             Created     0.1s

 ✔ Container docker-sandbox-1         Started     0.3s

 ✔ Container docker-db_postgres-1     Healthy     2.8s

 ✔ Container docker-web-1             Started     0.3s

 ✔ Container docker-redis-1           Started     0.3s

 ✔ Container docker-ssrf_proxy-1      Started     0.4s

 ✔ Container docker-weaviate-1        Started     0.3s

 ✔ Container docker-worker_beat-1     Started     3.2s

 ✔ Container docker-api-1             Started     3.2s

 ✔ Container docker-worker-1          Started     3.2s

 ✔ Container docker-plugin_daemon-1   Started     3.2s

 ✔ Container docker-nginx-1           Started     3.4s

Step 4: Verify the Deployment

Check that all containers are running:

docker compose ps

Every container should show a status of Up or healthy:

NAME                     IMAGE                              STATUS

docker-api-1             langgenius/dify-api:1.10.1         Up 22 seconds

docker-db_postgres-1     postgres:15-alpine                 Up 25 seconds (healthy)

docker-nginx-1           nginx:latest                       Up 22 seconds

docker-plugin_daemon-1   langgenius/dify-plugin-daemon:...  Up 22 seconds

docker-redis-1           redis:6-alpine                     Up 25 seconds (healthy)

docker-sandbox-1         langgenius/dify-sandbox:0.2.12     Up 25 seconds (healthy)

docker-ssrf_proxy-1      ubuntu/squid:latest                Up 25 seconds

docker-weaviate-1        semitechnologies/weaviate:1.27.0   Up 25 seconds

docker-web-1             langgenius/dify-web:1.10.1         Up 22 seconds

docker-worker-1          langgenius/dify-api:1.10.1         Up 22 seconds

docker-worker_beat-1     langgenius/dify-api:1.10.1         Up 22 seconds

If any container shows Exited or Restarting, check its logs:

# Replace 'api' with the service name that is failing

docker compose logs api --tail 100

Step 5: Access the Web Interface

Open your browser and navigate to:

http://localhost

The first time you visit, Dify will present an initialization screen where you set the admin email, username, and password. Complete this step to create your administrator account.

Customizing Your Deployment

The .env file in the dify/docker directory is the single source of truth for configuration. Here are the most important settings you should review and potentially modify.

Changing the Exposed Port

By default, Nginx listens on port 80. If you already have a service using that port, change it:

# In .env, find and modify:

EXPOSE_NGINX_PORT=80

EXPOSE_NGINX_SSL_PORT=443

# For example, change to:

EXPOSE_NGINX_PORT=8080

EXPOSE_NGINX_SSL_PORT=8443

After any .env change, restart the affected services:

docker compose down

docker compose up -d

Configuring the Vector Database

Dify defaults to Weaviate, but also supports Milvus, Qdrant, PgVector, OpenSearch, and others. To switch vector stores, modify the VECTOR_STORE variable in .env:

# Example: Switch to PgVector (uses the existing PostgreSQL instance)

VECTOR_STORE=pgvector

Each vector store has its own set of configuration variables (connection strings, API keys, etc.) documented in the .env.example file with inline comments.

Enabling File Upload Limits

Adjust the maximum file upload size for documents and images:

# Maximum file size in megabytes

FILES_MAXIMUM_SIZE=15

SMTP Email Configuration (Optional)

If you want features like email invitation for team members, configure SMTP:

MAIL_TYPE=smtp

MAIL_DEFAULT_SEND_FROM=noreply@yourdomain.com

SMTP_SERVER=smtp.yourdomain.com

SMTP_PORT=465

SMTP_USERNAME=your_username

SMTP_PASSWORD=your_password

SMTP_USE_TLS=true

Connecting Your First LLM Provider

Once Dify is running, the first thing you need to do is connect a language model. Navigate to Settings → Model Providers in the top-right corner menu.

Option A: Cloud Provider (OpenAI Example)

1. Click OpenAI (or your preferred provider) from the list.
2. Click Add Model or enter your API key directly.
3. Paste your API key and save.
4. Dify will validate the key and list available models (GPT-4o, GPT-4o-mini, etc.).

Option B: Local Model With Ollama

Running models locally eliminates API costs and keeps data entirely on your machine. First, set up Ollama:

# Install Ollama (Linux)

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

# Pull a model (for example, Qwen2.5 7B or Llama 3.1 8B)

ollama pull qwen2.5:7b

# Verify it is running

ollama list

Then in Dify:

1. Go to Settings → Model Providers.
2. Find Ollama in the list and click it.
3. Enter the base URL. Since Dify runs in Docker, use the host's IP address rather than localhost:
   code

   复制

   1	http://host.docker.internal:11434

   On Linux, you may need to use the actual host IP or add `--network host` to the Docker Compose configuration.

4. Save and select the model you pulled.

### Verifying the Connection

Create a new blank application (Chatbot type) and try sending a message. If the model responds, your setup is correct. If you get a connection error, double-check the API key and network configuration.

---

## Building Your First Application: A Simple Chatbot

Let's walk through creating a practical chatbot to solidify your understanding of the Dify interface.

### Creating the Application

1. On the Dify homepage, click **Create Blank App**.

2. Select **Chatbot** as the application type.

3. Give it a name, for example: "Technical Writing Assistant".

4. Click **Create**.

### Writing the System Prompt

In the **Orchestrate** tab, you will see a prompt editor. Write a clear system prompt that defines the bot's behavior:

You are an expert technical writer. Your job is to help users improve their technical documentation. Follow these rules:

1. Always use clear, concise language.
2. Prefer active voice over passive voice.
3. Suggest specific improvements rather than vague feedback.
4. When rewriting text, explain why your version is better.
5. If the user's text contains technical inaccuracies, point them out politely.

Begin by asking the user to paste the text they want help with.

### Adding Variables and Context

You can use template variables in your prompt with the `{{variable_name}}` syntax. For example, if you want to let users specify the target audience:

The target audience for this documentation is: {{audience}}.

Adjust your language complexity and examples accordingly.

When a user starts a conversation, Dify will prompt them to fill in the `audience` variable before proceeding.

### Testing in the Preview Panel

On the right side of the orchestrate page, you will find a **Preview** panel. Click it and interact with your bot. Verify that:

- It follows the system prompt correctly.

- It asks for text to review.

- It provides specific, actionable suggestions.

### Publishing Your Application

Once satisfied, click **Publish** in the top-right corner. Your chatbot is now accessible through:

- **Web App URL** — A shareable link that opens a standalone chat interface.

- **API Endpoint** — A REST API you can integrate into your own applications. Dify provides auto-generated API documentation with example code in Python, Node.js, and cURL.

Here is an example API call:

```python

import requests

import json

# Replace with your actual API key and endpoint

API_KEY = "app-your-api-key-here"

ENDPOINT = "http://localhost/v1/chat-messages"

headers = {

    "Authorization": f"Bearer {API_KEY}",

    "Content-Type": "application/json"

}

payload = {

    "inputs": {

        "audience": "junior developers with 1-2 years of experience"

    },

    "query": "Please review this paragraph: 'The system was designed for the purpose of facilitating the automization of the deployment process.'",

    "response_mode": "blocking",

    "conversation_id": "",

    "user": "test-user-001"

}

response = requests.post(ENDPOINT, headers=headers, json=payload)

result = response.json()

print(result["answer"])

Working With Knowledge Bases (RAG)

One of Dify's most powerful features is its built-in Retrieval-Augmented Generation (RAG) pipeline. You can upload documents, and Dify will automatically chunk, embed, and index them so your applications can search and cite the content.

Creating a Knowledge Base

1. Navigate to Knowledge in the top navigation bar.
2. Click Create Knowledge.
3. Name it (e.g., "Company FAQ").
4. Upload your documents. Dify supports TXT, Markdown, PDF, DOCX, HTML, CSV, and more.

Configuring Indexing Settings

After uploading, Dify asks you to configure how documents should be processed:

• Chunking strategy: Automatic (recommended for beginners) or custom. Custom chunking lets you set a specific character count and overlap.
• Embedding model: Choose from any embedding model available through your configured providers. A good default is text-embedding-3-small from OpenAI or a local embedding model via Ollama.
• Retrieval mode: Vector search (semantic), full-text search (keyword), or hybrid (both).

Connecting the Knowledge Base to Your Application

1. Open your chatbot's orchestrate page.
2. In the Context section, click Add.
3. Select your knowledge base.
4. Save and publish.

Now when users ask questions, the chatbot will first search the knowledge base for relevant chunks, include them as context in the prompt, and generate an answer grounded in your documents.

Best Practices for Knowledge Bases

• Clean your data: Garbage in, garbage out. Remove boilerplate text, headers/footers, and irrelevant sections before uploading.
• Use appropriate chunk sizes: 500-1000 tokens with 50-100 token overlap is a good starting point for most document types.
• Test retrieval quality: Use the Hit Testing feature in the knowledge base detail page to verify that queries return relevant chunks.
• Consider hybrid retrieval: Semantic search alone can miss exact keyword matches. Hybrid search combines both approaches for better accuracy.

Building Workflows for Complex Tasks

While chatbots handle conversational interactions, Workflows enable you to build deterministic, multi-step processing pipelines. Workflows are ideal for tasks like content generation, data transformation, or multi-source research.

Understanding the Workflow Canvas

When you create a Workflow application, you are presented with a visual canvas with these key node types:

• Start — Entry point that defines input variables.
• LLM — Calls a language model with a custom prompt.
• Knowledge Retrieval — Searches a knowledge base.
• Code — Executes Python or JavaScript code.
• HTTP Request — Calls an external API.
• Conditional Branch — Routes based on conditions (if/else logic).
• Iteration — Loops over a list of items.
• Template — Formats output using Jinja2 templates.
• End — Defines the final output.

Practical Example: Automated Article Summarizer

Let us build a workflow that takes a long article URL, fetches its content, summarizes it, and translates the summary into a target language.

Step 1 — Start Node

Define two input variables:

• url (string): The article URL.
• target_language (string): The desired output language (default: "English").

Step 2 — HTTP Request Node

Configure it to fetch the article:

• Method: GET
• URL: {{url}}
• Extract the response body text.

Step 3 — LLM Node (Summarization)

Prompt:

Summarize the following article in 3-5 bullet points. Focus on the key

arguments and conclusions.

Article content:

{{http_request.body}}

Step 4 — LLM Node (Translation)

Prompt:

Translate the following summary into {{target_language}}. Maintain the

bullet point format.

Summary to translate:

{{llm_1_output}}

Step 5 — End Node

Output the translated summary.

This simple workflow demonstrates how multiple nodes chain together to create a repeatable, reliable process. Each run produces consistent output regardless of how many times you execute it.

Advanced Features

MCP (Model Context Protocol) Integration

Dify supports the Model Context Protocol, an open standard that allows AI applications to securely connect with external tools and data sources. With MCP, your Dify applications can:

• Browse the web in real time
• Access databases and run SQL queries
• Interact with file systems
• Call any REST API through standardized tool definitions

To configure an MCP tool:

1. Navigate to Settings → Tools or the Tools section in your workspace.
2. Find the MCP-compatible tool you want to add.
3. Enter the MCP server URL and any required authentication credentials.
4. The tool becomes available in both chatbot and workflow applications.

Agents With Tool-Use

Agent applications give the LLM autonomy to decide which tools to use and in what order. Unlike workflows (which have a fixed execution path), agents dynamically plan their actions based on the user's request.

To create an Agent:

1. Create a new application and select Agent type.
2. Configure the system prompt and available tools.
3. Choose the reasoning strategy: Function Calling (for models that support it) or ReAct (for others).

Agents are powerful but less predictable than workflows. Use agents for open-ended tasks and workflows for well-defined processes.

Text-to-SQL and Data Analysis

Dify can connect directly to databases and allow natural language querying. The workflow is:

1. Connect a database (MySQL, PostgreSQL, etc.) through the tools configuration.
2. The LLM translates the user's natural language question into a SQL query.
3. The query executes against your database.
4. Results are returned to the LLM, which formats them as a human-readable answer or even generates an ECharts visualization.

This pattern is particularly valuable for internal analytics tools where non-technical team members need to query data.

Troubleshooting Common Issues

Containers Fail to Start

Symptom: One or more containers show Exited status.

Solution: Check logs with docker compose logs <service_name>. The most common causes are:

• Port conflicts (another service using port 80 or 443). Change EXPOSE_NGINX_PORT in .env.
• Insufficient memory. Increase Docker's memory limit in Docker Desktop settings.
• Corrupted .env file. Verify the syntax has no trailing spaces or missing quotes.

Knowledge Base Indexing Stuck at 0%

Symptom: Documents upload successfully but indexing never completes.

Solution: This usually indicates the embedding model is not configured or the Worker service is not running:

# Check worker logs

docker compose logs worker --tail 50

# Ensure you have a valid embedding model configured

# Go to Settings → Model Providers and verify an embedding model is available

Cannot Connect to Ollama From Docker

Symptom: Dify shows connection errors when trying to reach Ollama.

Solution: Docker containers cannot reach localhost on the host machine. Use:

• macOS/Windows: http://host.docker.internal:11434
• Linux: Add extra_hosts: ["host.docker.internal:host-gateway"] to the docker-compose.yaml under the API and Worker services, or use the host's actual IP address.

Slow Performance

Symptom: The interface is sluggish, and responses take a long time.

Solutions:

• Allocate more RAM to Docker (at least 8 GiB).
• Use a faster LLM (GPT-4o-mini instead of GPT-4, or a smaller local model).
• If using Weaviate with large datasets, consider switching to a dedicated vector database server.

Updating Dify to a New Version

To update your local Dify deployment to the latest release:

cd dify/docker

# Pull the latest images

docker compose pull

# Stop and remove existing containers

docker compose down

# Start with the new images

docker compose up -d

Important: Always back up your PostgreSQL data before major updates. Use docker compose exec db_postgres pg_dump -U postgres dify > backup.sql to create a backup.

Recommended Learning Path

Based on the comprehensive Dify learning curriculum from the community, here is a progressive path to master the platform:

Beginner (Week 1)

1. Complete local deployment (this guide).
2. Build a simple chatbot with prompt engineering.
3. Experiment with different LLM providers and compare outputs.

Intermediate (Weeks 2-3) 4. Create a knowledge base application with RAG. 5. Build a multi-step workflow for a content generation pipeline. 6. Set up an Agent with external tool access.

Advanced (Weeks 4+) 7. Implement Text-to-SQL for database querying. 8. Configure MCP tools for real-time web access. 9. Build a Deep Research agent that autonomously investigates complex topics. 10. Explore multi-modal capabilities (voice-to-text, image generation).

Conclusion

Deploying Dify locally gives you a powerful, private AI application development platform without recurring cloud costs or data privacy concerns. The Docker Compose deployment makes it accessible even to those without deep DevOps experience — a single docker compose up -d command brings up a complete production-grade stack.

The real value of Dify lies not just in its deployment simplicity, but in the breadth of capabilities it unlocks: visual workflow orchestration, RAG-powered knowledge bases, autonomous agents, database integrations, and MCP tool connectivity. Start with a simple chatbot, iterate toward more complex workflows, and gradually incorporate advanced features as your understanding deepens.

For further exploration, consult the official documentation at docs.dify.ai, join the community forum at forum.dify.ai, and follow the releases at github.com/langgenius/dify to stay current with new features and improvements.