Background Jobs

Overview

Documenso processes background jobs for email delivery, document sealing, webhook dispatch, and scheduled maintenance tasks. Three providers are available:

Select a provider with the NEXT_PRIVATE_JOBS_PROVIDER environment variable:

NEXT_PRIVATE_JOBS_PROVIDER=inngest  # or bullmq, local

Inngest (Recommended)

Inngest is a managed background job service. It handles scheduling, retries, concurrency, and observability without any infrastructure to manage. This is the recommended provider for production deployments.

Setup

1. Create an account at inngest.com
2. Create an app and obtain your event key and signing key
3. Configure the environment variables:

NEXT_PRIVATE_JOBS_PROVIDER=inngest
NEXT_PRIVATE_INNGEST_EVENT_KEY=your-event-key
INNGEST_SIGNING_KEY=your-signing-key

Environment Variables

Advantages

• No infrastructure to manage
• Built-in monitoring dashboard
• Automatic retries with backoff
• Cron scheduling handled externally
• Scales automatically

BullMQ

BullMQ is a Redis-backed job queue that runs inside the Documenso process. It provides higher throughput than the local provider, configurable concurrency, and a built-in dashboard for monitoring jobs.

Requirements

• Redis 6.2+ - any Redis-compatible service works (Redis, KeyDB, Dragonfly, AWS ElastiCache, Upstash, etc.)

Setup

NEXT_PRIVATE_JOBS_PROVIDER=bullmq
NEXT_PRIVATE_REDIS_URL=redis://localhost:6379

Environment Variables

Dashboard

BullMQ includes a job monitoring dashboard at /api/jobs/board. In production, only admin users can access the dashboard. In development, it is open to all users.

The dashboard provides visibility into queued, active, completed, and failed jobs.

Docker Compose with Redis

If you're using Docker Compose, add a Redis service:

services:
  redis:
    image: redis:8-alpine
    ports:
      - '6379:6379'
    volumes:
      - redis_data:/data

volumes:
  redis_data:

Then set NEXT_PRIVATE_REDIS_URL=redis://redis:6379 in your Documenso environment.

Advantages

• Self-hosted with no external service dependencies beyond Redis
• Configurable concurrency
• Built-in job monitoring dashboard
• Reliable retries with exponential backoff
• Queue namespacing for shared Redis instances

Local

The local provider uses your PostgreSQL database as a job queue. Jobs are stored in the BackgroundJob table and processed via internal HTTP requests that Documenso sends to itself.

Setup

No configuration required. The local provider is the default when NEXT_PRIVATE_JOBS_PROVIDER is unset or set to local.

# Optional - this is the default
NEXT_PRIVATE_JOBS_PROVIDER=local

Internal URL

Background jobs in the local provider work by Documenso sending HTTP requests to itself. If your reverse proxy or network setup causes issues with the app reaching its own public URL, set the internal URL:

NEXT_PRIVATE_INTERNAL_WEBAPP_URL=http://localhost:3000

This tells the job system to use the internal address instead of NEXT_PUBLIC_WEBAPP_URL for self-requests.

Limitations

• No concurrency control - jobs are processed one at a time per request cycle
• No built-in monitoring
• Depends on the application being able to reach itself over HTTP
• Not suitable for high-throughput workloads

Choosing a Provider

See Also

• Environment Variables - Complete configuration reference
• Requirements - Infrastructure requirements
• Docker Compose - Deploy with Docker Compose