egeominotti/bunqueue repository overview

High-performance job queue server for Bun.
Memory or one-file SQLite by default, PostgreSQL 15–18 multi-broker when you scale.
DLQ, cron, priorities, flows, S3 backups and Prometheus metrics. No Redis.

Documentation⁠ · Quick Start⁠ · Deployment guide⁠ · GitHub⁠ · npm⁠

⁠Quick reference

• Maintained by: bunqueue contributors⁠
• Where to get help: Documentation⁠ · GitHub Issues⁠
• Source of these images: Dockerfile⁠, built, tested and published by GitHub Actions⁠
• Architectures: linux/amd64, linux/arm64 (Docker selects the matching one)
• Also published at: ghcr.io/egeominotti/bunqueue, with the same tags
• Changelog: bunqueue.dev/changelog⁠
• License: MIT⁠

⁠Supported tags

All four variants run the same server with the same features, protocols and persistence options. Only the Linux base and the tools inside the container differ.

• Alpine: compact default, with a shell and apk.
• Distroless: minimal attack surface; operate it through logs and health checks (docker exec ... sh is unavailable).
• Debian slim / Debian: glibc and apt, when you need Debian compatibility or familiar tooling.

Moving tags follow new releases. For production, pin a version tag, or a digest to pin the exact image.

⁠Quick start

docker run -d --name bunqueue \
  --restart unless-stopped \
  -p 127.0.0.1:6789:6789 \
  -p 127.0.0.1:6790:6790 \
  -v bunqueue-data:/app/data \
  egeominotti/bunqueue:2.9.20

curl --fail http://127.0.0.1:6790/health

This binds both APIs to your machine only. Drop the 127.0.0.1: prefix to expose them on the network, and enable authentication first (see below).

⁠Connect a client

npm install bunqueue-client

import { Queue, Worker } from 'bunqueue-client';

const options = { embedded: false, connection: { host: '127.0.0.1', port: 6789 } };

const queue = new Queue('emails', options);
const worker = new Worker('emails', async (job) => {
  console.log('Processing:', job.data.to);
  return { sent: true };
}, options);

await queue.add('welcome', { to: '[email protected]' });

Official clients are also available for Deno, Python, PHP, Go, Rust and Elixir. See the Quick Start⁠ for each language.

⁠Docker Compose

services:
  bunqueue:
    image: egeominotti/bunqueue:2.9.20
    restart: unless-stopped
    ports:
      - '6789:6789' # TCP (SDK clients)
      - '6790:6790' # HTTP (health, metrics, REST)
    volumes:
      - bunqueue-data:/app/data
    environment:
      AUTH_TOKENS: ${AUTH_TOKENS}

volumes:
  bunqueue-data:

⁠Ports, volume and runtime

Probe endpoints: /healthz (liveness), /ready (readiness) and /health (health plus memory). /health and /ready return 503 when persistent storage is degraded.

⁠Configuration

Configure the server with environment variables. The most common ones:

Clients authenticate with connection: { token: '...' }. The full list is in the environment variables reference⁠.

⁠Scaling with PostgreSQL

Run several active brokers against one PostgreSQL 15–18 database by setting BUNQUEUE_STORAGE_DRIVER=postgres and the same BUNQUEUE_POSTGRES_URL (and BUNQUEUE_POSTGRES_NAMESPACE, if you set one) on every replica. The repository ships a ready-made docker-compose.postgres.yml⁠, and the deployment guide⁠ covers Kubernetes manifests, probes and connection budgeting.

⁠Supply-chain security

Every variant is tested on both architectures before it is published. Since 2.9.13, release images are signed with GitHub artifact attestations (Sigstore, no keys to manage): build provenance on Docker Hub and GHCR, plus a CycloneDX SBOM (linux/amd64). Verify an image before deploying it:

gh attestation verify oci://docker.io/egeominotti/bunqueue:2.9.20 --repo egeominotti/bunqueue

Add --predicate-type https://cyclonedx.org/bom and use the ghcr.io reference to verify the SBOM.

⁠Features

• Queues: priorities, delays, FIFO/LIFO, FIFO groups, deduplication and custom IDs, rate limits, concurrency limits
• Reliability: retries with backoff, dead-letter queue, stall detection, leases, durable writes
• Scheduling: cron and fixed-interval jobs with time zones
• Orchestration: parent/child flows and job dependencies
• Operations: Prometheus metrics, webhooks, S3 backups, and the bunqueue CLI inside the image

The bunqueue⁠ npm package adds a workflow engine with saga compensation and an MCP server for AI agents; both can connect to this server over TCP.

⁠License

bunqueue is released under the MIT License⁠.