Dify Backend API
Setup and Run
uv, Docker Compose, and the Node.js and pnpm versions pinned in the root package.json are required. Run the commands below from the repository root, with each long-running service in its own terminal.
Using scripts (recommended)
-
Run setup for a new checkout (copies env files and installs dependencies). This overwrites
api/.env,web/.env.local, anddocker/middleware.env; preserve existing configuration before rerunning it../dev/setup -
Review
api/.env,web/.env.local, anddocker/middleware.envvalues (see theSECRET_KEYnote below). -
Start middleware (PostgreSQL/Redis/Weaviate).
./dev/start-docker-compose -
Start backend (runs migrations first).
./dev/start-api -
Start Dify web service.
./dev/start-web./dev/setupand./dev/start-webinstall JavaScript dependencies through the repository root workspace, so you do not need a separatecd web && pnpm installstep. -
Set up your application by visiting
http://localhost:3000. -
Start the worker service (executes queued async tasks).
./dev/start-worker -
Start Celery Beat when scheduled tasks are needed. This is required when
KNOWLEDGE_FS_LIFECYCLE_WORKER_ENABLED=trueso provisioning and deletion outbox commands are dispatched to the lifecycle worker../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.
Leave SECRET_KEY empty to let Dify generate a persistent key in the storage directory. To manage it explicitly, generate a value with openssl rand -base64 42 and set SECRET_KEY in api/.env.
Testing
Run from the repository root:
uv sync --project api --group dev
make test
make test TARGET_TESTS=./api/tests/unit_tests/<path>
make lint
make type-check
make test includes provider unit tests and runs controller tests separately. Integration suites are CI-only and are not expected to run locally. Test environment defaults live in api/pyproject.toml under tool.pytest_env; see the backend agent guide for package conventions.
API contracts
The API schema guide owns schema changes and verification. Generate the OpenAPI specifications and TypeScript/Zod contracts through the workspace script:
pnpm -C packages/contracts gen-api-contract
Refresh the checked-in Markdown reference with:
uv run --project api python api/dev/generate_swagger_markdown_docs.py \
--swagger-dir packages/contracts/openapi --markdown-dir api/openapi/markdown --keep-swagger-json
Update the backend schema owner and regenerate contracts instead of converting types manually or editing generated files.