This page documents how to configure a local development environment for the Dify platform. It covers prerequisites, setup scripts, service orchestration, devcontainer usage, and debugging configurations. For information about testing infrastructure, see Testing Infrastructure and Strategies For deployment configurations, see Environment Configuration and Runtime Modes
This guide provides instructions for:
uv for Python, pnpm for Node.js).The Dify development environment requires specific package managers and runtimes:
| Tool | Purpose | Version |
|---|---|---|
uv | Python package and project management | 0.8.9+ api/README.md7-9 |
pnpm | Node.js package management | Latest web/README.md12 |
| Node.js | Frontend runtime | 22.x (LTS) web/Dockerfile2 |
| Python | Backend runtime | >=3.10 api/pyproject.toml4 |
| Docker | Middleware services | 20.x+ |
Sources: api/pyproject.toml4 api/README.md7-9 web/Dockerfile2 web/README.md12
The architecture comprises setup scripts that provision environment files, install dependencies, and start runtime services including API backend, frontend web, worker processes, and middleware services.
Sources: api/README.md18-57 web/README.md39-62 dev/setup1
The repository provides helper scripts in the dev/ directory for setting up the environment and starting services. The recommended approach is running ./dev/setup which automates environment preparation and dependency installation.
The dev-setup operation performs these key tasks:
docker/envs/middleware.env.example to docker/middleware.env and starts middleware containers (PostgreSQL, Redis, Weaviate).web/.env.example to web/.env.local and installs JS dependencies using pnpm install.api/.env.example to api/.env, installs Python dependencies with uv sync --group dev, and runs database migrations.These tasks are orchestrated mainly by the dev/setup script and the repository Makefile targets.
Sources: dev/setup1 Makefile18-47
After running setup, you should review and customize these environment configuration files:
| File | Purpose | Key Variables |
|---|---|---|
api/.env | Backend configuration | SECRET_KEY, DB_*, REDIS_*, VECTOR_STORE |
web/.env.local | Frontend configuration | NEXT_PUBLIC_API_URL, NEXT_PUBLIC_DEPLOY_ENV, NEXT_PUBLIC_COOKIE_DOMAIN |
docker/middleware.env | Docker Compose defaults | CONSOLE_API_URL, DB_PASSWORD, VECTOR_STORE, REDIS_* |
The backend requires a SECRET_KEY for session cookie signing and security. If omitted, Dify tries to self-generate one and persist it in the app storage location. It is recommended to generate your own persistent key:
Linux:
Mac:
Sources: api/README.md65-79
Middleware services include PostgreSQL, Redis, Weaviate, sandbox workers, and plugin daemon. These are defined in docker/docker-compose.middleware.yaml and managed via:
This script uses Docker Compose with environment file docker/middleware.env to spin up required middleware containers.
Sources: docker/docker-compose.middleware.yaml1-215 dev/start-docker-compose1
The backend API runs on port 5001 by default. The dev/start-api script launches it, running database migrations before starting the Flask app.
Worker processes handle asynchronous tasks such as indexing and workflow executions. Use:
This script runs the Celery worker with configurable pools, concurrency, and queues. It uses uv to run the Python environment with Celery.
Sources: dev/start-api1 dev/start-worker1-129
The frontend uses Next.js with PNPM for management. Start it via:
This script runs pnpm dev or uses vinext for improved dev experience.
Sources: web/README.md53-57 dev/start-web1
The repository includes a VS Code devcontainer setup for an isolated, reproducible dev environment.
It uses python:3.12-bookworm base image with system libraries installed for Python numeric computations and development.
This image installs the uv package manager for Python and enables corepack (Node.js) for PNPM.
Sources: .devcontainer/Dockerfile1-11
On devcontainer creation, .devcontainer/post_create_command.sh runs, which:
pnpm installuv globally with pipxSources: .devcontainer/post_create_command.sh1-17
The .vscode/launch.json.template file includes curated debug configurations for backend and frontend development.
Python: API
Runs the API server via the python interpreter located at ${workspaceFolder}/api/.venv/bin/python. Typical args include running api/app.py with FLASK_APP=app.py environment to start the Flask app.
This allows setting breakpoints and debugging API logic.
Sources: .vscode/launch.json.template5-13
Python: Celery Worker
Runs the Celery worker module (celery) with arguments -A app.celery worker -P solo.
The solo pool runs all tasks in a single process, which is crucial to enabling debugger breakpoints in async task execution code.
Sources: .vscode/launch.json.template15-36
Next.js: Web Frontend
Executes the Next.js CLI binary directly with the --inspect flag to enable Node.js debugging.
It includes serverReadyAction to launch Chrome debugger automatically upon server startup detection.
Sources: .vscode/launch.json.template38-52
The development environment is designed to support rapid iteration and debugging of all core Dify components:
uv for Python dependency and environment management.pnpm with a Next.js/Vite+ based setup for fast builds and test execution.This setup balances local development agility with reproducibility and compatibility across development team members.
Sources:
api/README.md7-79 web/README.md12-62 web/Dockerfile2
dev/setup1 Makefile18-47 docker/docker-compose.middleware.yaml1-215
dev/start-docker-compose1 dev/start-api1 dev/start-worker1-129 dev/start-web1
.devcontainer/Dockerfile1-11 .devcontainer/post_create_command.sh1-17 .vscode/launch.json.template1-55
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.