Dify Backend API

Setup and Run

[!IMPORTANT]

In the v1.3.0 release, poetry has been replaced with uv as the package manager for Dify API backend service.

uv and pnpm are required to run the setup and development commands below.

Using scripts (recommended)

The scripts resolve paths relative to their location, so you can run them from anywhere.

Run setup (copies env files and installs dependencies).
bash
```
./dev/setup
```
Review api/.env, web/.env.local, and docker/middleware.env values (see the SECRET_KEY note below).
Start middleware (PostgreSQL/Redis/Weaviate).
bash
```
./dev/start-docker-compose
```
Start backend (runs migrations first).
bash
```
./dev/start-api
```
Start Dify web service.
bash
```
./dev/start-web
```
./dev/setup and ./dev/start-web install JavaScript dependencies through the repository root workspace, so you do not need a separate cd web && pnpm install step.
Set up your application by visiting http://localhost:3000.
Start the worker service (async and scheduler tasks, runs from api).
bash
```
./dev/start-worker
```
Optional: start Celery Beat (scheduled tasks).
bash
```
./dev/start-beat
```

Environment notes

[!IMPORTANT]

When the frontend and backend run on different subdomains, set COOKIE_DOMAIN to the site’s top-level domain (e.g., example.com). The frontend and backend must be under the same top-level domain in order to share authentication cookies.

Generate a SECRET_KEY in the .env file.

bash for Linux

bash

sed -i "/^SECRET_KEY=/c\\SECRET_KEY=$(openssl rand -base64 42)" .env

bash for Mac

bash

secret_key=$(openssl rand -base64 42)
sed -i '' "/^SECRET_KEY=/c\\
SECRET_KEY=${secret_key}" .env

Testing

Install dependencies for both the backend and the test environment
bash
```
cd api
uv sync --group dev
```

Run the tests locally with mocked system environment variables in tool.pytest_env section in pyproject.toml, more can check Claude.md

bash

cd api
uv run pytest                           # Run all tests
uv run pytest tests/unit_tests/         # Unit tests only
uv run pytest tests/integration_tests/  # Integration tests

# Code quality
./dev/reformat               # Run all formatters and linters
uv run ruff check --fix ./   # Fix linting issues
uv run ruff format ./        # Format code
uv run basedpyright .        # Type checking

Generate TS stub

uv run dev/generate_swagger_specs.py --output-dir openapi

use https://jsontotable.org/openapi-to-typescript to convert to typescript