dify/api/README.md

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)

1. Run setup for a new checkout (copies env files and installs dependencies). This overwrites api/.env, web/.env.local, and docker/middleware.env; preserve existing configuration before rerunning it.

   ./dev/setup
   

2. Review api/.env, web/.env.local, and docker/middleware.env values (see the SECRET_KEY note below).

3. Start middleware (PostgreSQL/Redis/Weaviate).

   ./dev/start-docker-compose
   

4. Start backend (runs migrations first).

   ./dev/start-api
   

5. Start Dify web service.

   ./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.

6. Set up your application by visiting http://localhost:3000.

7. Start the worker service (executes queued async tasks).

   ./dev/start-worker
   

8. Optional: start Celery Beat (scheduled tasks).

   ./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.

Upgrading workflow task cancellation

When upgrading from a version that did not persist workflow_runs.task_id, stop new workflow admissions and drain the old workers before switching versions. Old running tasks have no recoverable task-to-run index; do not terminate them by guessing a run ID or using an unscoped Redis fallback.

After applying database migrations, keep API traffic and workflow consumers stopped and recover paused task IDs from their existing storage snapshots:

uv run --project "$PWD/api" --directory api flask backfill-workflow-task-ids

Run this with the deployment's database and storage configuration. The command processes bounded batches and can be rerun. It exits unsuccessfully if legacy running records or missing/invalid pause snapshots remain; inspect the reported run and repair its state before retrying. It preserves run ownership and skips pauses changed by another worker. Once it succeeds, start the new API and workers. Fresh installations need no backfill.

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.