Local Development

Set up the source code with a minimal authless run or a seeded PostgreSQL and Redis stack.

All commands on this page run from the repository root unless stated otherwise. For a deployed instance, use Installation.

Prerequisites

Bun 1.3.5, the version used by the repository and CI.
Node.js 20.19+ or 22.12+ for the Vite web app.
A reachable Redis instance, or Docker with Compose to start one.

git clone https://github.com/durabullhq/durabull.git
cd durabull
bun install --frozen-lockfile

Option A: Minimal local run

Use this path to try the dashboard without configuring login or PostgreSQL. If Redis is not already running, start a disposable local instance:

docker run -d --name durabull-dev-redis -p 127.0.0.1:6379:6379 redis:8-alpine

Then start the API and web app:

bun run dev:authless

Open http://localhost:5173. The API runs at http://localhost:3001/api; Vite proxies API and MCP requests from the web origin.

The launcher supplies defaults for authless mode, environment-managed connections, a MAIN connection at redis://localhost:6379, and development-only secrets. Existing shell variables override those defaults. It does not start Redis or unset DATABASE_URL.

If a repository .env already configures PostgreSQL and you want PGlite instead, run:

DATABASE_URL= bun run dev:authless

To use another Redis instance, set the connection explicitly:

DURABULL_REDIS_URL_MAIN=redis://localhost:56379 bun run dev:authless

Authless mode gives every visitor owner access. Keep this development stack on a trusted machine or behind access controls. An empty Redis instance has no queues to display.

Option B: Full stack with sample data

This path starts PostgreSQL and Redis in Docker and creates sample users, organizations, queues, jobs, and schedulers.

Copy the example configuration:
```
cp .env.example .env
openssl rand -hex 32
```
In .env, replace DURABULL_REDIS_URL_ENCRYPTION_KEY with the generated value. Generate a separate value for DURABULL_SECRET_ENCRYPTION_KEY and another random secret for BETTER_AUTH_SECRET. Leave DURABULL_AUTHLESS and DURABULL_ENV_CONNECTIONS unset or false for the authenticated, database-managed workflow.

.env is a dotenv file: paste the generated values into it. Shell expressions such as $(openssl rand -hex 32) are not evaluated when the file is loaded.
Start infrastructure and seed it:
```
bun docker
bun docker:seed
```
Defaults are PostgreSQL at localhost:55432 and Redis at localhost:56379. If you change DURABULL_POSTGRES_PORT or DURABULL_REDIS_PORT, update DATABASE_URL or REDIS_URL to match.
Start the app:
```
bun run dev
```
Open http://localhost:5173 and sign in with admin@example.com / password. Select Acme Corporation → Acme Production to explore the seeded data. These credentials are for disposable development data only.

For mock workers, run bun docker:seed:workers; that command stays running until you stop it.

Generate continuous demo traffic

bun run dev starts only the API and web app. To add the workload generator in a separate terminal:

bun run workload:dev

Or start the API, web app, and workload together:

bun run dev:demo

The workload uses WORKLOAD_REDIS_URL, then REDIS_URL, then redis://127.0.0.1:6379. It resets its known demo queues on startup by default. Use a disposable Redis database; see the fleet workload guide for isolation and retention settings.

Check your setup

curl -fsS http://localhost:3001/api/health
curl -fsS http://localhost:3001/api/mode

Health should report status: "ok"; mode should match your authentication, connection, and persistence choices. Then verify connections, queues, job details, schedulers, and workers in the UI. Health confirms that the API responds; it does not test every Redis connection.

Work on the docs

bun run dev:docs

Open http://localhost:3002/documentation. To validate the documentation site:

bun run --filter @durabull/docs typecheck
bun run build:docs

Reset development data

bun docker:down stops containers without deleting their volumes. Starting them again preserves existing data.

bun docker:wipe deletes data from the configured development database and Redis instance. Check the targets in .env before running it, then use bun docker:seed to recreate sample data. bun docker:reset removes Docker volumes and recreates the infrastructure.