Dify Local Deployment Guide: Full Walkthrough with BT Panel + Docker

What Is Dify? Why Is It Worth Learning?

Dify is an open-source large language model (LLM) application development platform that combines the concepts of Backend as a Service (BaaS) and LLMOps.

LLMOps (Large Language Model Operations) is an extension of MLOps into the era of large models, covering the full lifecycle management of LLM applications—from development, testing, and deployment to monitoring. BaaS (Backend as a Service) is a cloud service model in which developers don't need to build and maintain their own server infrastructure and can directly invoke the backend capabilities provided by the platform. Dify combines the two, meaning developers can enjoy out-of-the-box AI backend services while also performing fine-grained operational management of model calls, prompts, and data pipelines.

The Technical Lineage of LLMOps: LLMOps evolved from MLOps (Machine Learning Operations), and MLOps itself is an extension of DevOps concepts into the AI domain. Traditional MLOps focuses on model training, feature engineering, and model serving; LLMOps builds on this by adding new operational dimensions specific to large models, such as prompt version management, model A/B testing, token usage monitoring, and conversation log analysis. Typical representatives of the BaaS model include Firebase, Supabase, and others, which allow front-end developers to build complete applications without backend knowledge. By combining these two concepts, Dify essentially provides AI applications with an integrated platform offering "full-stack hosting + fine-grained operations."

It's worth noting that the core difference between LLMOps and traditional MLOps lies in the shift of the iteration target: the core iteration unit of traditional MLOps is model weights (improving results through retraining), whereas the core iteration unit of LLMOps is prompts and context engineering (improving results by adjusting the System Prompt, Few-shot examples, and retrieval strategies). This shift makes "prompt version control" and "conversation quality evaluation" first-class citizens in the LLMOps toolchain, and Dify's prompt orchestration and log tracing features are a direct response to this need.

Its core value lies in this: whether you're a professional developer or a non-technical person, you can quickly build production-grade generative AI applications.

For developers, Dify comes with the key technology stack needed to build LLM applications—support for hundreds of models, an intuitive prompt orchestration interface, and a built-in high-quality RAG (Retrieval-Augmented Generation) engine.

RAG Technical Background: RAG (Retrieval-Augmented Generation) is one of the most mainstream technical paradigms in current enterprise-grade AI applications. Its core idea is: before handing a user's question to the large model for an answer, first retrieve relevant content from an external knowledge base (such as enterprise documents or databases), then feed both the retrieval results and the question into the model. This gives the model's answers both powerful reasoning capabilities and the ability to incorporate the latest, private knowledge. This approach effectively solves the LLM's "hallucination" problem and knowledge cutoff limitations, and is the foundational architecture for building enterprise intelligent customer service and document Q&A systems.

The engineering implementation of RAG involves two key stages: the offline indexing stage (chunking documents, vectorizing them, and storing them in a vector database) and the online retrieval stage (vectorizing the user's question and retrieving the most semantically similar text chunks from the database). Dify's built-in RAG engine handles all the details of both stages, including document parsing, chunking strategies (fixed-size / semantic chunking), embedding model selection (such as text-embedding-3-small), and retrieval algorithms (vector retrieval / keyword retrieval / hybrid retrieval). On the vector database side, Dify supports mainstream solutions like Weaviate, Qdrant, Milvus, and pgvector, allowing developers to choose flexibly based on data scale and performance requirements.

In practical engineering, the quality of RAG results depends largely on the choice of chunking strategy: fixed-size chunking is simple to implement but may cut off content at semantic boundaries; semantic chunking splits based on paragraph structure or sentence similarity, preserving more complete semantic units but at a higher computational cost. In addition, hybrid search (combining vector similarity retrieval with BM25 keyword retrieval) typically delivers more stable recall quality than a single retrieval method, because vector retrieval excels at handling semantically ambiguous questions, while keyword retrieval is more reliable for exact-match needs involving proper nouns, code snippets, and the like.

This means you don't have to "reinvent the wheel" from scratch and can focus your energy on business innovation instead.

If we compare the common development library LangChain to a "toolbox" (containing hammers, nails, and all sorts of tools), then Dify is more like a complete "scaffolding"—it not only provides tools but has also gone through complete engineering design and software testing, and can directly support a fully functional application. More importantly, Dify is open-source and free, so you can freely extend it as you see fit.

The Positioning Difference Between LangChain and Dify: LangChain is a Python/JavaScript development framework that provides low-level abstractions for model invocation, chained reasoning, Memory management, tool integration, and more—suitable for developers with programming skills to build customized AI applications with code. Dify, on the other hand, builds a complete product layer on top of underlying libraries like LangChain, offering out-of-the-box features such as a visual orchestration interface, user management, API publishing, and monitoring dashboards. The two are not competitors—Dify's own underlying implementation actually uses some LangChain components. A more accurate analogy is: LangChain is the "engine," and Dify is the "complete vehicle." For teams looking to quickly validate a product idea or build internal tools, Dify offers a higher degree of engineering readiness; for scenarios requiring deep customization of reasoning logic, using frameworks like LangChain directly is more flexible.

Which Models Does Dify Support?

Dify offers fairly comprehensive compatibility with mainstream large models both at home and abroad:

• Foreign models: OpenAI (GPT series), Google Gemini, Cohere, and more
• Domestic models: Zhipu, Baichuan, iFlytek Spark, Tongyi Qianwen, ERNIE Bot, Doubao, DeepSeek, Moonshot AI, and more

In the model list, Dify uses icons to mark model capabilities: the hammer icon indicates that the model supports tool calling (Function Calling), and the glasses icon indicates support for vision (multimodal) capabilities.

An Analysis of Function Calling Capability: Function Calling (tool calling) refers to a large language model's ability, during a conversation, to recognize user intent and proactively invoke external functions or APIs to obtain real-time information or perform actions. For example, when a user asks "What's the weather like in Beijing today?", a model with Function Calling capability won't make something up out of thin air, but instead calls a pre-registered weather query tool to obtain real data before answering. This is the core capability for building AI Agents—without tool calling, an Agent can only "talk" but cannot "act." OpenAI was the first to standardize this capability in 2023, and domestic models like DeepSeek and Moonshot AI later followed suit.

At the technical implementation level, Function Calling works by injecting tool descriptions (function signatures in JSON Schema format) into the model's System Prompt, guiding the model to output structured JSON call instructions when needed. The caller (such as Dify's Agent module) parses this JSON, executes the corresponding external function, injects the result into the conversation context, and then lets the model generate the final answer based on the real data. This "reason → call → reason again" loop is exactly the core of the ReAct Agent architecture. It's worth noting that different models vary in tool-calling stability and their ability to invoke multiple tools in parallel, so it's advisable to test with your actual business scenarios when making a selection.

Engineering Background of Multimodal Capability: The vision capability (Vision/multimodal) represented by the glasses icon means the model can accept images as input, understand image content, and reason in combination with text instructions. The underlying architecture of such models (like GPT-4o, Gemini 1.5 Pro, and the Claude 3 series) typically uses a vision encoder (such as CLIP or ViT) to convert images into vector representations, which are then fed into a Transformer decoder along with text tokens. In Dify's workflow scenarios, multimodal capability can be used to build applications for image content moderation, receipt recognition, chart interpretation, and more; in chat application scenarios, users can directly upload screenshots or product images to ask the AI questions, greatly expanding the boundaries of interaction.

If you plan to build an Agent capable of calling tools, you'll need to pick a model marked with the "hammer" icon—domestic models like DeepSeek and Moonshot AI also have tool-calling capabilities.

Preparing for Deployment: Virtual Machine and System Environment

Dify supports multiple deployment methods, including running from source, Docker deployment, and more. Based on hands-on comparison, this article recommends the most beginner-friendly approach—local deployment via BT Panel.

This approach requires two things:

1. Virtual machine software: VMware Workstation or VMware Player (used to run the Linux system)
2. Linux system image: Ubuntu 22.04

VMware Virtualization Technology Background: VMware adopts a Type-2 Hypervisor (hosted virtual machine monitor) architecture, running on top of the host operating system and simulating a complete hardware environment (CPU, memory, disk, network card) through software to run guest operating systems. Compared with installing Linux directly on a physical machine, the virtual machine approach has these advantages: you can create snapshots at any time (saving the current state and rolling back with one click if something goes wrong), disk files can be copied and migrated, and it doesn't affect the host system. VMware Workstation Pro has been free for individual users since 2024, and VMware Player has always been a free version. If you're using an Apple Silicon Mac, consider UTM or Parallels Desktop as alternatives; if you're operating in a native Linux or WSL2 environment, you can skip the virtual machine step and proceed directly to the subsequent deployment.

Why Choose Ubuntu 22.04 LTS: Ubuntu 22.04 is a Long-Term Support (LTS) version released by Canonical, with an official commitment to provide security patches and maintenance updates until 2027—making it more suitable as a server base system than short-cycle versions. Ubuntu's compatibility in the Docker ecosystem has been the most extensively validated, and the vast majority of Docker images are built and tested with Ubuntu as the baseline environment. In addition, the Linux kernel version used by 22.04 (5.15 LTS) fully supports underlying features that Docker relies on, such as cgroups v2 and OverlayFS, effectively avoiding container runtime issues seen on some older systems.

Installing the virtual machine is very simple—just double-click the installer and keep clicking "Next." Here's an important reminder: neither the VMware software itself nor the subsequent virtual machine system should be installed on the C drive, because a large number of cache files are generated during operation, which can easily fill up the system drive.

Creating and Installing an Ubuntu Virtual Machine

After opening VMware, select "Create a New Virtual Machine" → "I will install the operating system later" → choose the "Linux" system with the version set to Ubuntu 64-bit. When allocating disk space to the virtual machine, if it's only used to deploy Dify, 20GB is more than enough, and it's recommended to choose "Split virtual disk into multiple files."

The newly created virtual machine is an "empty shell" that can't be started directly, because there's no operating system inside yet. Next, in the virtual machine settings, find the "CD/DVD" option, select "Use ISO image file," and mount the downloaded Ubuntu image into it—this is equivalent to "inserting an installation disc" into the computer.

After starting the virtual machine, select "Try or Install Ubuntu" to enter the installation interface. Choose "Chinese (Simplified)" for the language and keep the default keyboard layout. For the installation type, just choose "Minimal installation" (if you also need to do other Linux development, you can choose "Normal installation").

When the system indicates that the disk has no operating system, there's no need to worry—this just means the allocated 20GB space is empty. Simply select "Erase disk" and "Install Now." After setting up a username and password (it's recommended to check "Log in automatically" to save yourself the hassle of entering the password each time), just wait for the installation to complete.

After the installation is complete, the system will prompt a restart. Once you remove the image disc, you can enter a brand-new Ubuntu desktop.

Installing BT Panel

With the Ubuntu system in place, the next step is to install BT Panel—it turns the subsequent Docker and Dify deployment into a "point-and-click" visual operation, greatly reducing reliance on the command line.

The Technical Positioning of BT Panel: BT Panel is essentially a web console program running on a Linux server, written in Python, that manages services such as Nginx, Apache, MySQL, and PHP by invoking system commands. It transforms server operations that originally required extensive command-line knowledge (such as configuring virtual hosts, managing SSL certificates, and viewing system resources) into visual web interface operations. In the VPS operations scenario for domestic small and medium-sized enterprises and individual developers, BT Panel holds a very high market share. Note that the panel itself consumes a certain amount of system resources and may affect performance on machines with less than 1GB of memory; for production environments, it's recommended to change the default port and enable security entrance verification to improve security.

Visit the BT Panel official website, select "Linux Panel" → "Install Free Version," and be careful to avoid the advertisement links at the top of the page. Choose Ubuntu based on your system version, then copy the installation command.

Back in the virtual machine, use the shortcut Ctrl + Alt + T to open the terminal, paste the command, and press Enter. The system will ask you to enter your password (note that when entering a password in a Linux terminal, no characters are displayed—this is normal). Once confirmed, the installation begins.

After the installation is complete, BT Panel will output a set of key information: the panel login address, username, and default password. Since this is a local deployment, you can simply use the "internal network address" to access it. Copy the address into your browser to open it, and enter the username and password to log in to BT Panel.

Customizing Panel Security Settings

The first login will require you to read the agreement and bind an account. After entering the panel, it's recommended to change the default login port, password, and security entrance to make access more convenient and secure.

Besides modifying it on the web interface, you can also run the bt command (an abbreviation for Bট Panel) in the virtual machine terminal to restart the panel, change the port, and modify the password and security entrance through the command-line menu. For example, change the default complex port to an easy-to-remember 8899, and change the lengthy security entrance to an easy-to-remember name like bthou.

Deploying Dify via Docker

Docker is currently the most mainstream containerization platform. Its core idea is to package an application and all its dependencies (runtime, libraries, configuration files) into a standardized "container image." The benefit of this is that no matter which machine you run the image on, the application behaves exactly the same, completely solving the classic deployment problem of "it works on my machine."

Dify is deployed using Docker Compose, and a single command can simultaneously launch multiple service components including the front end, back end, database, and vector database—greatly simplifying what would otherwise be a complex distributed application deployment process.

The Relationship Between Docker and Docker Compose: Docker solves the problem of packaging and running a single application, while Docker Compose solves the orchestration problem of multi-container applications. Dify's complete operation requires multiple independent services working together: Nginx (reverse proxy), the Web front end, the API back end (Python/Flask), Worker for asynchronous task processing, PostgreSQL (a relational database that stores user data), Redis (cache and message queue), and a vector database (such as Weaviate). Docker Compose describes the dependencies, network configurations, and data volume mounts of these services through a YAML configuration file (docker-compose.yml). After running docker-compose up, all services can be launched with one click in the correct order, and they are ensured to communicate with each other within the same virtual network.

The Underlying Mechanism of Containerization: A Docker container is not a virtual machine—it doesn't simulate complete hardware but shares the host's Linux kernel, achieving lightweight isolation through Linux Namespaces (process, network, and filesystem isolation) and cgroups (CPU and memory resource limits). A container's filesystem is built in layers based on OverlayFS: image layers (read-only) + container layer (writable). This allows multiple containers to share the read-only layers of the same image, greatly saving disk space. Precisely because there's no need to simulate hardware, Docker container startup time is usually on the order of seconds, whereas a virtual machine's startup often takes tens of seconds or even longer. For an application like Dify that contains 7–8 service components, using Docker Compose for unified management is much cleaner than installing native services one by one on the system, and it's also easier to migrate and roll back versions.

BT Panel has a built-in Docker module, which makes Dify's local deployment extremely simple.

First, find "Docker" on the left side of BT Panel, click "Install," and keep the default installation method. Docker installation takes some time, so just be patient. After a successful installation, refresh the page to see the Docker-related features.

Next, search for "Dify" in Docker's app store, click "Install," and confirm. The application name can be customized or kept as the default.

Common Deployment Issues and Solutions

In practice, Dify installation failure is the most common problem beginners encounter. Here are three typical situations and their corresponding solutions:

Issue 1: Version Installation Error

If the installation hangs for a long time or even reports errors like BTFile, first uninstall it, then search for Dify again, change the version to 1.00, and try installing again.

Issue 2: Docker Image Pull Failure (Network Issue)

If you still get errors after changing the version and can't pull the image, it's usually a DNS configuration issue.

DNS and Image Pull Principles: DNS (Domain Name System) is responsible for resolving domain names into IP addresses. By default, a virtual machine inherits the host's DNS configuration, which in certain network environments may fail to correctly resolve the domain name of Docker Hub (Docker's official image registry), causing image pulls to fail. Changing the DNS to Google's public DNS (8.8.8.8 and 8.8.4.4) can improve resolution stability. It's worth understanding that /etc/resolv.conf is the DNS configuration file of the Linux system, and the nameserver field specifies the DNS server address the system prioritizes when querying domain names; this file may be reset by the network manager after a system restart. To make changes permanent, you can persist the settings by modifying /etc/systemd/resolved.conf or the NetworkManager configuration.

The solution steps are as follows:

1. In the virtual machine terminal, run nano /etc/resolv.conf
2. Change nameserver to 8.8.8.8, and add a new line nameserver 8.8.4.4
3. Save and exit (Ctrl+O to confirm, Ctrl+X to leave)
4. Run the relevant commands to restart the panel and clear the cache

Issue 3: Still Unable to Pull Images After Changing DNS

Due to network access restrictions, slow or failed direct connections to Docker Hub from within China is a common problem. You can configure a mirror acceleration address in Docker settings—the principle is to forward image requests to domestic cache nodes such as Alibaba Cloud or Tencent Cloud, bypassing the direct-connection bottleneck. Click "Help" to enter the BT Panel tutorial, find the acceleration links, fill them in one by one and test them. After making the changes, restart Docker to pull images normally.

How Docker Image Acceleration Works: A Docker image is composed of multiple layers, each corresponding to an instruction in the Dockerfile, and the layers are identified by content addressing (SHA256 hash). When you run docker pull, the Docker client sends a request to the image registry to download the compressed packages of each layer. Docker Hub's servers are located overseas, and pulling from within China is limited by international bandwidth, making it extremely slow or even causing timeouts. An image accelerator (Mirror) works like this: a reverse proxy node is deployed within China, and when you request an image from the acceleration address, if the node has already cached the image it returns it directly; otherwise, it pulls the image from Docker Hub, caches it, and forwards it. Alibaba Cloud, Tencent Cloud, and Huawei Cloud all provide such services, and among them, Alibaba Cloud's acceleration address requires logging into an account to obtain a personal dedicated address. After configuring an accelerator, docker pull speed can typically improve from tens of KB/s to several MB/s or even higher.

Completing Deployment and Accessing Dify

When Dify's status changes to "Running," copy its access address and make two adjustments:

• Change https to http
• Change the port to 8088, and append /install after it

For example, accessing http://internal-IP:8088/install will take you to Dify's initial installation interface. After setting up the administrator email and username, Dify's local deployment is complete.

Summary

This article has laid out the complete process of deploying Dify locally via BT Panel: from understanding the positioning and model support of this open-source LLM application development platform, to setting up a VMware virtual machine and the Ubuntu system, then installing BT Panel and Docker, and finally completing Dify's local deployment.

The core advantage of this entire approach lies in replacing complex command-line operations with a graphical panel, allowing even beginners with no operations experience to smoothly go through the process. The vast majority of image pull failures encountered during deployment can be resolved by changing the DNS or configuring image acceleration.

Completing the local deployment is just the first step. Afterward, you can build intelligent chatbots on Dify, configure Agent toolboxes, design automated workflows, mount knowledge bases (RAG), and ultimately publish your own AI applications as public sites or APIs.

Key Takeaways