Architecture and Modes
Understand how authentication, Redis connection management, and database persistence work together.
Durabull has an API (apps/api), a React dashboard (apps/web), a documentation site (apps/docs),
and an Electron desktop shell (apps/desktop). The API performs BullMQ operations against your
Redis instances and stores Durabull configuration in PostgreSQL or PGlite.
Production containers and desktop builds serve the dashboard from the API process. MCP runs
in that same process at /mcp. In local development, Vite serves the dashboard and proxies
requests to the API.
Choose authentication and connection management
The two settings are independent:
| Setting | true | false or unset |
|---|---|---|
DURABULL_AUTHLESS | Bypass login and initialize a local user with owner access | Authenticate users through Better Auth |
DURABULL_ENV_CONNECTIONS | Define Redis connections with DURABULL_REDIS_URL_*; disable connection create/edit/delete | Manage Redis connections through the UI and API |
Environment-managed connections are still synchronized into the Durabull database for each organization. The toggle changes who manages the connection definitions; it does not eliminate the database or make queue/job actions read-only.
Choose persistence
| Configuration | Database | What to preserve |
|---|---|---|
DATABASE_URL set | PostgreSQL | Database backups and encryption keys |
DATABASE_URL empty or unset | File-backed PGlite | PGlite data directory and encryption keys |
PGlite defaults to data/pglite relative to the API process's working directory. With
bun run dev, that is normally apps/api/data/pglite; in the production container it is
/app/data/pglite. Set DURABULL_PGLITE_DIR for an explicit location.
The API reports stateless: true for PGlite mode. That field means an external PostgreSQL server
is unnecessary; PGlite still stores users, settings, and alert state on disk. Mount persistent
storage for containers and use PostgreSQL when multiple API replicas need to share state.
BullMQ jobs, logs, schedulers, and queue metrics remain in Redis. Backing up the Durabull database does not back up those jobs.
Common configurations
| Use case | Authentication | Connections | Persistence |
|---|---|---|---|
| Local evaluation | Authless | Environment-managed | PGlite |
| Desktop app defaults | Authless | UI-managed | PGlite in Electron's user-data directory |
| Small authenticated instance | Better Auth | Either source | PGlite with persistent storage |
| Team deployment | Better Auth | Either source | PostgreSQL |
Authless mode gives everyone who can reach the app owner access. Use authenticated mode for internet-facing deployments. Team invitations require authenticated users.
Check the active configuration with GET /api/mode. Continue with
Authentication and Organizations,
Connection Management, or
Environment Variables.