### Install Dependencies and Run Authless Source: https://github.com/durabullhq/durabull/blob/main/README.md Installs project dependencies and starts the application in an authless mode for local development. This mode is not recommended for public internet exposure. ```bash bun install bun run dev:authless ``` -------------------------------- ### Run Full Demo Stack in One Terminal Source: https://github.com/durabullhq/durabull/blob/main/README.md Starts the API, web application, and workload generator simultaneously in a single terminal for a convenient demo setup. ```bash bun run dev:demo ``` -------------------------------- ### Environment Variable Example (.env.example) Source: https://github.com/durabullhq/durabull/blob/main/PLAN-ALERTING-SYSTEM.md Provides example configuration for environment variables related to the alerting system in a .env.example file. ```dotenv # Alerting # DURABULL_ALERT_ENABLED=true # Enable/disable background alert monitor # DURABULL_ALERT_POLL_INTERVAL_MS=60000 # Alert polling interval in ms (default: 60s) ``` -------------------------------- ### Create Docker Network and Start Redis Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/self-hosting/installation.mdx Creates a Docker network named 'durabull' and starts a Redis instance within it. This is the first step for a Docker-based Durabull installation. ```bash docker network create durabull docker run -d --name durabull-redis --network durabull redis:8-alpine ``` -------------------------------- ### Start Durabull Development Server from Source Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/self-hosting/installation.mdx Starts the Durabull development server with authless mode enabled. This command is used after installing from source and configuring environment variables. ```bash bun run dev:authless ``` -------------------------------- ### Install Dependencies from Source Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/self-hosting/installation.mdx Installs project dependencies using Bun. This command is used when installing Durabull from source code. ```bash bun install ``` -------------------------------- ### Desktop Build Commands Source: https://github.com/durabullhq/durabull/blob/main/apps/desktop/README.md Execute these commands from the repo root to build, start, or distribute the desktop application. ```bash bun run build:desktop ``` ```bash bun run start:desktop ``` ```bash bun run dist:desktop ``` -------------------------------- ### Example Log Line Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/log-formatting-and-highlighting.mdx An example of a log line formatted according to the recommended structure, demonstrating timestamp, level, context, message, and key-value fields. ```text [2026-02-13T21:25:43.232Z] [INFO] [SYNC] Processing adjustment | jobId=sync-adjustment-123 | queue=shipment-rebill | attempt=3 ``` -------------------------------- ### Quick Start Durabull with Docker Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/deployment/docker.mdx Starts Redis and Durabull in authless mode for local evaluation. Ensure to use explicit version tags for production. ```bash docker network create durabull docker run -d --name durabull-redis --network durabull redis:8-alpine docker run --rm -p 127.0.0.1:3000:3000 --network durabull \ -e DURABULL_AUTHLESS=true \ -e MCP_AUTHLESS_BEARER_TOKEN="$(openssl rand -hex 32)" \ -e DURABULL_ENV_CONNECTIONS=true \ -e DURABULL_REDIS_URL_ENCRYPTION_KEY=$(openssl rand -hex 32) \ -e DURABULL_REDIS_URL_MAIN=redis://durabull-redis:6379 \ -e DURABULL_REDIS_URL_MAIN_ENVIRONMENT=development \ -e DURABULL_REDIS_URL_DEFAULT=MAIN \ -e APP_BASE_URL=http://localhost:3000 \ -e VITE_PUBLIC_APP_URL=http://localhost:3000 \ ghcr.io/durabullhq/durabull:latest ``` -------------------------------- ### Good Log Example Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/log-formatting-and-highlighting.mdx An example of a well-formatted log line that adheres to best practices for clarity and searchability. ```text [2026-02-13T21:25:43.232Z] [ERROR] [SYNC] Request failed | jobId=sync-adjustment-123 | requestId=req_516c2008d9054dc2 | status=404 ``` -------------------------------- ### Start Fleet Demo Workload Source: https://github.com/durabullhq/durabull/blob/main/packages/fleet-demo-workload/README.md Execute the fleet demo workload using Bun. This command can be run directly or by navigating to the workload's directory. ```bash bun --filter @durabull/fleet-demo-workload start ``` ```bash cd packages/fleet-demo-workload bun run start ``` -------------------------------- ### Setup Full Local Stack with Docker Source: https://github.com/durabullhq/durabull/blob/main/README.md Sets up the full local Durabull stack using Docker, including seeding data. This is for a comprehensive local development environment. ```bash bun docker bun docker:seed bun run dev ``` -------------------------------- ### Bad Log Example Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/log-formatting-and-highlighting.mdx An example of a poorly formatted log line that lacks structure, making it difficult to parse and search effectively. ```text something failed maybe 404 id 123 retrying ??? {"huge":"payload", ...} ``` -------------------------------- ### Run App Services Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/getting-started/local-development.mdx Starts the API and web application services. This command is used after infrastructure is running and data is seeded. ```bash bun run dev ``` -------------------------------- ### Run Demo Traffic Generator Source: https://github.com/durabullhq/durabull/blob/main/README.md Starts a demo traffic generator to simulate workload against the local Durabull instance. This is an optional step for testing. ```bash bun run workload:dev ``` -------------------------------- ### Start Local Infrastructure with Docker Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/getting-started/local-development.mdx Initiates the local Docker stack including Postgres and Redis. Ensure no other local Postgres container uses Durabull's default host port. ```bash bun docker ``` -------------------------------- ### Install Durabull with Homebrew on macOS Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/getting-started/desktop-apps.mdx Use this command to install Durabull on Apple Silicon macOS via Homebrew. This is recommended for repeatable rollouts on managed fleets. ```bash brew install --cask durabullhq/tap/durabull ``` -------------------------------- ### Server-side API Setup with @durabull/auth Source: https://github.com/durabullhq/durabull/blob/main/packages/auth/README.md Configure the authentication handler for your API server. Ensure the baseURL matches your server's address. ```typescript import { createAuth } from '@durabull/auth' const auth = await createAuth({ baseURL: 'http://localhost:3001', }) // Use auth.handler for handling auth requests app.all('/api/auth/*', (c) => auth.handler(c.req.raw)) ``` -------------------------------- ### Seed Local Development Data Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/getting-started/local-development.mdx Populates the local database with realistic development data. This command should be run after starting the infrastructure. ```bash bun docker:seed ``` -------------------------------- ### Start and Stop Alert Monitor Source: https://github.com/durabullhq/durabull/blob/main/PLAN-ALERTING-SYSTEM.md Adds imports and calls to start and stop the background alert monitoring service within the application's lifecycle management. ```typescript import { startAlertMonitor, stopAlertMonitor } from './lib/alert-monitor' ``` ```typescript startAlertMonitor() ``` ```typescript console.log(`[shutdown] Received ${reason}, stopping alert monitor...`) stopAlertMonitor() ``` -------------------------------- ### Configure Environment Variables for Source Install Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/self-hosting/installation.mdx Sets environment variables in a .env file for a self-hosted Durabull installation from source. This includes settings for authentication, connections, Redis, and base URLs. ```bash DURABULL_AUTHLESS=true DURABULL_ENV_CONNECTIONS=true DURABULL_REDIS_URL_ENCRYPTION_KEY= DURABULL_REDIS_URL_MAIN=redis://localhost:6379 DURABULL_REDIS_URL_MAIN_ENVIRONMENT=development DURABULL_REDIS_URL_DEFAULT=MAIN APP_BASE_URL=http://localhost:5173 VITE_PUBLIC_APP_URL=http://localhost:5173 ``` -------------------------------- ### Start Alert Monitor Source: https://github.com/durabullhq/durabull/blob/main/PLAN-ALERTING-SYSTEM.md Starts the alert monitor service. It includes a random jitter for the initial poll to prevent a thundering herd. This function should be called once on API boot. ```typescript let pollTimer: ReturnType | null = null let isRunning = false /** * Start the alert monitor. Called once on API boot. * Adds random jitter to first poll to avoid thundering herd. */ export function startAlertMonitor(): void { if (isRunning) return isRunning = true const jitter = Math.floor(Math.random() * MAX_STARTUP_JITTER_MS) console.log(`[alert-monitor] Starting in ${(jitter / 1000).toFixed(0)}s...`) setTimeout(() => { void runPollCycle() pollTimer = setInterval(() => void runPollCycle(), POLL_INTERVAL_MS) }, jitter) } ``` -------------------------------- ### POST /queues/:queueName/jobs Request Body Example Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/reference/http-api.mdx This JSON object demonstrates the structure for creating a new job with optional BullMQ job options such as delay, priority, and retry configurations. ```json { "name": "send-welcome-email", "data": { "userId": "123" }, "delay": 5000, "priority": 5, "attempts": 3, "backoff": { "type": "exponential", "delay": 1000 }, "removeOnComplete": 100, "removeOnFail": true } ``` -------------------------------- ### Docker Compose Setup for Durabull Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/deployment/docker.mdx Launches Durabull and Redis using Docker Compose for a self-hosted deployment. Defaults to production-ready settings, disabling authless mode. ```bash export DURABULL_REDIS_URL_ENCRYPTION_KEY="$(openssl rand -hex 32)" export BETTER_AUTH_SECRET="$(openssl rand -hex 32)" # Optional for production: export APP_BASE_URL=https://your-domain.example docker compose -f tooling/docker/docker-compose.self-hosted.yaml up -d ``` -------------------------------- ### Self-hosted Docker MCP Quick Check Source: https://github.com/durabullhq/durabull/blob/main/docs/mcp-operations-runbook.md Performs a quick check of the MCP endpoint after starting a self-hosted Docker environment. Verifies API health and the OAuth protected resource. ```bash export APP_BASE_URL=http://localhost:3000 curl -fsS "$APP_BASE_URL/api/health" curl -fsS "$APP_BASE_URL/.well-known/oauth-protected-resource" | jq .resource ``` -------------------------------- ### JSON Payload in Log Example Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/log-formatting-and-highlighting.mdx Shows how JSON fragments within a log line are highlighted but treated as text. Keep JSON compact and consider job data storage for large payloads. ```text [2026-02-13T21:25:43.232Z] [INFO] Payload received | data={"adjustmentId":"abc123","mode":"dry-run"} ``` -------------------------------- ### Build Unpacked App Bundle Source: https://github.com/durabullhq/durabull/blob/main/apps/desktop/README.md If you only need the unpacked app bundle for a quick local sanity check, run this command. ```bash bun run dist:desktop:dir ``` -------------------------------- ### Initialize Hono App for Alerts Source: https://github.com/durabullhq/durabull/blob/main/PLAN-ALERTING-SYSTEM.md Sets up a Hono application instance for handling alert-related API routes. Assumes connection middleware is already applied. ```typescript import { alertEventRepository, alertRuleRepository } from '@durabull/dal' import { zValidator } from '@hono/zod-validator' import { Hono } from 'hono' import { z } from 'zod' const app = new Hono() ``` -------------------------------- ### Get Job Stacktraces Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/job-lifecycle-and-debugging.mdx Retrieves paginated stacktraces for a specific job. ```APIDOC ## GET /api/c/:connectionId/queues/:queueName/jobs/:jobId/stacktraces ### Description Retrieves paginated stacktraces associated with a specific job. Stacktraces are stored as an array in the job hash. ### Method GET ### Endpoint `/api/c/:connectionId/queues/:queueName/jobs/:jobId/stacktraces` ``` -------------------------------- ### Get Job Logs Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/job-lifecycle-and-debugging.mdx Retrieves paginated logs for a specific job. ```APIDOC ## GET /api/c/:connectionId/queues/:queueName/jobs/:jobId/logs ### Description Retrieves paginated logs associated with a specific job. ### Method GET ### Endpoint `/api/c/:connectionId/queues/:queueName/jobs/:jobId/logs` ``` -------------------------------- ### Publish Desktop App Directly Source: https://github.com/durabullhq/durabull/blob/main/apps/desktop/README.md To publish directly from a macOS machine instead of CI, run this command from the 'apps/desktop' directory with a GitHub token available as GH_TOKEN. This uses electron-builder's direct GitHub publish path. ```bash bun run dist:publish ``` -------------------------------- ### GET /api/c/:connectionId/alerts/rules Source: https://github.com/durabullhq/durabull/blob/main/PLAN-ALERTING-SYSTEM.md Retrieves a list of all alert rules associated with a specific connection. ```APIDOC ## GET /api/c/:connectionId/alerts/rules ### Description Retrieves a list of all alert rules associated with a specific connection. ### Method GET ### Endpoint `/api/c/:connectionId/alerts/rules` ### Parameters #### Path Parameters - **connectionId** (string) - Required - The ID of the connection. ### Response #### Success Response (200) - **rules** (array) - An array of alert rule objects. - **rule** (object) - Contains details of an alert rule. #### Response Example ```json { "rules": [ { "id": "string", "name": "string", "type": "string", "queueName": "string", "config": {}, "notificationChannels": [], "cooldownMinutes": 0, "enabled": true, "createdAt": "string", "updatedAt": "string" } ] } ``` ``` -------------------------------- ### Lint, Typecheck, and Build Docs App Source: https://github.com/durabullhq/durabull/blob/main/tasks/todo.md Commands to run linting, type checking, and building the documentation application. These are typically used to ensure code quality and prepare the application for deployment. ```bash bun run lint bun run typecheck bun run build ``` -------------------------------- ### Get Current Session Source: https://github.com/durabullhq/durabull/blob/main/packages/auth/README.md Retrieves information about the current user's active session. ```APIDOC ## GET /api/auth/session ### Description Retrieves the details of the currently active user session. ### Method GET ### Endpoint /api/auth/session ### Response #### Success Response (200) - **user** (object) - User details if authenticated - **isAuthenticated** (boolean) - True if a session is active, false otherwise ``` -------------------------------- ### Get Workers Source: https://github.com/durabullhq/durabull/blob/main/tasks/mcp-implementation-master-plan.md Retrieves snapshots of workers, optionally filtered by queue. This endpoint provides visibility into the worker pool. ```APIDOC ## Tool: `get_workers` ### Description Retrieves snapshots of workers, optionally filtered by queue. This endpoint provides visibility into the worker pool. ### Input - `connectionId` (string) - The ID of the connection. - `queueFilter?` (string) - Optional filter to specify a particular queue. ### Output - `workers` (array) - An array of worker snapshots. ``` -------------------------------- ### MCP Server Execution Playbook - PR Stack Overview Source: https://github.com/durabullhq/durabull/blob/main/tasks/mcp-pr-execution-playbook.md Overview of the sequential PR stack for MCP server development, from security architecture to production readiness. ```markdown - PR-01: Security architecture + ADR + threat model + scope taxonomy - PR-02: API-mounted MCP module (`/mcp`) + transport wiring + conformance harness - PR-03: OAuth discovery (PRM/WWW-Authenticate) + MCP token validation middleware - PR-04: Principal model (delegated users + service accounts) + policy engine - PR-05: Read-only tool set for jobs/failures/logs/diagnostics - PR-06: Output safety (redaction), rate limits, and audit logging - PR-07: Cloud deployment path + self-host deployment path + runbooks - PR-08: Production readiness verification, security review closure, GA docs ``` -------------------------------- ### Get Job Stacktraces Source: https://github.com/durabullhq/durabull/blob/main/tasks/mcp-implementation-master-plan.md Retrieves attempt-indexed stacktrace entries for a specific job, facilitating the analysis of errors and exceptions. ```APIDOC ## Tool: `get_job_stacktraces` ### Description Retrieves attempt-indexed stacktrace entries for a specific job, facilitating the analysis of errors and exceptions. ### Input - `connectionId` (string) - The ID of the connection. - `queueName` (string) - The name of the queue. - `jobId` (string) - The ID of the job. - `pagination` (object) - Pagination parameters. ### Output - `stacktraceEntries` (array) - An array of attempt-indexed stacktrace entries. ``` -------------------------------- ### Run Unit Tests in apps/web Source: https://github.com/durabullhq/durabull/blob/main/tasks/handoff-analytics-mcp-telemetry.md Execute unit tests for specific components and routes within the 'apps/web' directory. This is part of the additional P3 verification process. ```bash bun run test:unit src/components/app-update-banner.test.tsx src/routes/settings.test.tsx src/routes/queue-detail-scheduled-create.test.tsx src/routes/queue-detail-remove.test.tsx src/routes/job-detail-remove.test.tsx ``` -------------------------------- ### Get Job Source: https://github.com/durabullhq/durabull/blob/main/tasks/mcp-implementation-master-plan.md Retrieves the full, safe details of a specific job identified by its connection, queue, and job ID. ```APIDOC ## Tool: `get_job` ### Description Retrieves the full, safe details of a specific job identified by its connection, queue, and job ID. ### Input - `connectionId` (string) - The ID of the connection. - `queueName` (string) - The name of the queue. - `jobId` (string) - The ID of the job. ### Output - `jobDetail` (object) - The full, safe details of the job. ``` -------------------------------- ### Get Queue Source: https://github.com/durabullhq/durabull/blob/main/tasks/mcp-implementation-master-plan.md Retrieves detailed information about a specific queue, including its detail, count summary, and pause state. ```APIDOC ## Tool: `get_queue` ### Description Retrieves detailed information about a specific queue, including its detail, count summary, and pause state. ### Input - `connectionId` (string) - The ID of the connection. - `queueName` (string) - The name of the queue. ### Output - `queueDetail` (object) - Detailed information about the queue. - `countSummary` (object) - Summary of counts for the queue. - `pauseState` (boolean) - The pause state of the queue. ``` -------------------------------- ### Build Local Mac App Artifacts Source: https://github.com/durabullhq/durabull/blob/main/apps/desktop/README.md Run these commands from the repo root on macOS to produce packaged desktop artifacts, including .dmg and .zip targets. ```bash bun run build:desktop ``` ```bash bun run dist:desktop ``` -------------------------------- ### Simulate Worker Activity Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/getting-started/local-development.mdx Optionally runs a simulation for worker processes. This can be run alongside seeding or after the main application services are started. ```bash bun docker:seed:workers ``` -------------------------------- ### Develop Fleet Demo Workload Source: https://github.com/durabullhq/durabull/blob/main/packages/fleet-demo-workload/README.md Run the fleet demo workload in development mode. Ensure Redis is accessible at the configured WORKLOAD_REDIS_URL. ```bash cd packages/fleet-demo-workload bun run dev ``` -------------------------------- ### Build Order for AI Agents Source: https://github.com/durabullhq/durabull/blob/main/PLAN-ALERTING-SYSTEM.md This outlines the phased build order for the alerting system, indicating dependencies between phases and their respective deliverables. ```text Phase 1: Database schemas + repositories (DAL package only, no API changes) Phase 2: Alert evaluator (pure functions, no dependencies beyond types) Phase 3: Alert monitor background loop (depends on Phase 1 + 2) Phase 4: Alert notifier + email template (depends on Phase 1, uses @durabull/email) Phase 5: API routes (depends on Phase 1, wires up Phase 3 + 4) Phase 6: Integration — mount routes, start monitor on boot Phase 7: Frontend (out of scope for now) ``` -------------------------------- ### Alert Monitor Startup Banner Source: https://github.com/durabullhq/durabull/blob/main/PLAN-ALERTING-SYSTEM.md Defines a string to be displayed in the startup banner, indicating that the alert monitor is active. ```typescript const alertBanner = '🔔 Alerts: Monitor active' ``` -------------------------------- ### Get Failure Events Source: https://github.com/durabullhq/durabull/blob/main/tasks/mcp-implementation-master-plan.md Retrieves alert or failure event records with safe context, optionally filtered by connection, queue, job, or status. ```APIDOC ## Tool: `get_failure_events` ### Description Retrieves alert or failure event records with safe context, optionally filtered by connection, queue, job, or status. ### Input - `connectionId` (string) - The ID of the connection. - `queueName?` (string) - Optional filter by queue name. - `jobId?` (string) - Optional filter by job ID. - `status?` (string) - Optional filter by status. - `offset` (integer) - The offset for retrieving events. - `limit` (integer) - The limit for the number of events to retrieve. ### Output - `failureEvents` (array) - An array of alert/failure event records with safe context. ``` -------------------------------- ### Queue Naming Format Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/naming-best-practices.mdx Use a stable, descriptive format for queue names, typically ... Ensure names are lowercase and use a consistent separator. ```text .. ``` ```text billing.invoice.sync ``` ```text notifications.email.send ``` ```text orders.fulfillment.reconcile ``` -------------------------------- ### Get Job List Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/job-lifecycle-and-debugging.mdx Retrieves a list of jobs within a specific queue. Supports filtering by status and job name, as well as pagination. ```APIDOC ## GET /api/c/:connectionId/queues/:queueName/jobs ### Description Retrieves a list of jobs for a given queue, with support for filtering by status and job name, and pagination. ### Method GET ### Endpoint `/api/c/:connectionId/queues/:queueName/jobs` ### Parameters #### Query Parameters - **status** (string) - Optional - Filter jobs by their status. - **name** (string) - Optional - Filter jobs by their name. - **page** (integer) - Optional - The page number for pagination. - **pageSize** (integer) - Optional - The number of jobs to return per page. ``` -------------------------------- ### Recommended Production Environment Variables Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/getting-started/environment-variables.mdx A baseline set of environment variables for a production Durabull deployment. Ensure secrets are kept secure and generated appropriately. ```bash NODE_ENV=production APP_BASE_URL=https://your-domain.example VITE_PUBLIC_APP_URL=https://your-domain.example DURABULL_AUTHLESS=false BETTER_AUTH_SECRET= DURABULL_REDIS_URL_ENCRYPTION_KEY= DURABULL_SECRET_ENCRYPTION_KEY= DURABULL_ENV_CONNECTIONS=true DURABULL_REDIS_URL_MAIN=redis://... DURABULL_REDIS_URL_MAIN_ENVIRONMENT=production DURABULL_REDIS_URL_DEFAULT=MAIN ``` -------------------------------- ### Structured Segment Example Source: https://github.com/durabullhq/durabull/blob/main/apps/docs/content/documentation/workflows/log-formatting-and-highlighting.mdx Demonstrates using the '|' delimiter to separate logical parts of a log line, which aids in scanning and highlighting key-value pairs. ```text [2026-02-13T21:25:43.232Z] [DEBUG] Recomputing totals | orderId=ord_123 | attempt=2 | source=worker ``` -------------------------------- ### Get Queue Metrics Source: https://github.com/durabullhq/durabull/blob/main/tasks/mcp-implementation-master-plan.md Retrieves metrics for a specific queue, including completed/failed windows, rates, and streaks, optionally within a specified time window. ```APIDOC ## Tool: `get_queue_metrics` ### Description Retrieves metrics for a specific queue, including completed/failed windows, rates, and streaks, optionally within a specified time window. ### Input - `connectionId` (string) - The ID of the connection. - `queueName` (string) - The name of the queue. - `windowMinutes?` (integer) - Optional time window in minutes. ### Output - `metrics` (object) - An object containing queue metrics such as completed windows, failed windows, rates, and streaks. ```