How to Install Dify Locally (Step-by-Step Guide)

Introduction

Running Dify locally gives you full control over your AI application development environment, your data, and your models. This guide walks through deploying the Dify community edition on your own machine using Docker Compose, with all the required services—database, vector store, and application layers—packaged together. No prior Dify experience is needed, only familiarity with a terminal and Docker.

Prerequisites

• Docker & Docker Compose – Ensure Docker Engine 20.10+ and Docker Compose v2 are installed.
• Git – Required to clone the repository.
• System resources – Minimum 4 CPU cores, 8 GB RAM, and 10 GB free disk space recommended.
• Terminal access – Basic command‑line experience for editing files and running docker compose commands.
• LLM API key (optional for full functionality) – e.g., OpenAI, Azure OpenAI, Anthropic. You can add it after installation.

Step 1: Clone the Dify Repository

Open a terminal and clone the official repository, then navigate into the project directory:

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

The repository contains everything needed: Docker Compose files, environment templates, and documentation.

Step 2: Configure the Environment

Dify includes a pre‑configured .env.example file with sensible defaults. Copy it to create your own .env file:

cp .env.example .env

Edit the .env file only if you need to:

• Change the default PostgreSQL password (POSTGRES_PASSWORD)
• Set a custom secret key for the application (SECRET_KEY)
• Pre‑configure an LLM provider key (e.g., OPENAI_API_KEY)

For a basic local trial, the defaults are sufficient. You can add your LLM API key later through the web UI.

Step 3: Start All Services with Docker

From the dify/ directory, run:

docker compose up -d

This command starts the following containers:

Service	Role
api	Core backend API that handles workflows, RAG, and users
web	React‑based frontend UI
db	PostgreSQL database for metadata and user data
redis	Cache and message queue
weaviate	Default vector store for RAG (can be swapped later)
worker	Background task processing (async document indexing, etc.)
nginx	Reverse proxy that routes traffic to api/web

Pull times depend on your network. After the containers are healthy, Dify is running locally.

Step 4: Access the Dify UI

Open your browser and navigate to:

http://localhost

The Nginx reverse proxy binds to port 80 by default. If you need to change the port, edit the docker-compose.yaml or set EXPOSE_NGINX_PORT in .env.

Step 5: Initial Setup

1. Create an admin account – On first visit, you’ll be prompted to set up an email and password for the workspace administrator.
2. Configure workspace – Name your workspace (e.g., “Local Dev”).
3. Connect an LLM provider – Go to Settings → Model Provider and add an API key for the model you want to use (OpenAI, Azure, Anthropic, Ollama for local models, etc.). You can also skip this and add it later, but the platform will not generate responses without a provider.

After this step, you can create your first AI application.

Architecture Overview

Your local deployment follows this request path:

Browser → Nginx (port 80) → Dify Web (React) / Dify API (Flask)
                              ↳ API → Workflow Engine → LLM Provider
                                ↳ Vector DB (Weaviate) for RAG
                                ↳ PostgreSQL for metadata

All components run inside Docker containers, isolated from your host system except for volumes used for persistent data.

Troubleshooting

Docker port conflict (port 80 already in use)

If port 80 is occupied, edit the .env file and change EXPOSE_NGINX_PORT to another value, e.g., 8080. Then restart:

docker compose down
docker compose up -d

Access the UI at http://localhost:8080.

API key errors or “No model available”

• Verify you’ve entered the correct API key in Settings → Model Provider.
• For local models via Ollama, ensure Ollama is running and the base URL is accessible from within the Dify container (use host.docker.internal or the host’s LAN IP).

Database connection failure

Check if the PostgreSQL container is healthy:

docker compose ps

If db shows unhealthy, inspect logs:

docker compose logs db

Common causes: insufficient disk space, permission issues on the mounted volume, or a leftover postgres process on the host. Resolve by removing the volume and restarting:

docker compose down -v
docker compose up -d

UI not loading / blank page

• Ensure the web container is running: docker compose ps.
• Clear your browser cache or try a private window.
• Check browser console for errors. If static files are not loading, the API might be unreachable; verify that nginx is up and listening on the correct port.

Verification

To confirm everything is working:

1. Open http://localhost (or your custom port).
2. Log in with the admin account you created.
3. Navigate to Studio and create a new app (e.g., “Chat App”).
4. In the app builder, write a simple test prompt and run it. If you receive a coherent response from the LLM, your local Dify installation is fully operational.

Summary

You now have a self‑hosted Dify instance running locally. The platform is ready for building RAG‑based Q&A systems, chatbots, and AI workflows without relying on external cloud services. From here, you can integrate your own knowledge bases, connect additional model providers, and publish apps via API or the built‑in web interface.