Bun 队列

Docker images

All four images run the same bunqueue server with the same queue features, protocols, and persistence options. The difference is the Linux base and the tools available inside the container.

Starting with 2.9.5, completed releases publish to both Docker Hub (egeominotti/bunqueue) and GHCR (ghcr.io/egeominotti/bunqueue), with matching version, latest, and variant tags. Build references are kept on GHCR only. Each image supports linux/amd64 and linux/arm64; Docker selects the matching architecture automatically. You choose the distribution, not the CPU tag. Pin a version or digest for reproducible deployments. Confirm a tag exists with docker buildx imagetools inspect egeominotti/bunqueue:<tag> before using it.

Choose a Linux distribution with the same tags on either registry:

Which variant should I use?

- Alpine is the default for a compact deployment. It uses musl and includes a shell and the apk package manager. Choose it when you do not need Debian tooling or glibc compatibility for additional software. - Debian uses glibc and the standard Debian base, with a shell and apt. Choose it when familiar Debian tools and a fuller base matter more than image size. Additional troubleshooting tools may still need to be installed. - Debian slim keeps glibc, a shell, and apt in a reduced Debian base. Choose it when you want Debian compatibility with fewer bundled utilities. - Distroless contains the compiled server and its required runtime libraries, without a shell or package manager. Choose it when you operate through logs, health checks, and external debugging tools; docker exec ... sh is unavailable.

The distribution does not select a faster queue engine or unlock extra features. All images run as a non-root user; having a package manager does not grant that user permission to install packages at runtime.

Try a specific variant by changing only the image tag:

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-alpine

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

This example exposes the APIs only on your machine. Replace 2.9.20-alpine with 2.9.20-debian, 2.9.20-slim, or 2.9.20-distroless to choose another base. Moving tags such as alpine follow newer releases; version tags identify a release, while a digest pins the exact image even across base-image rebuilds.

Every variant supports both architectures, runs as UID/GID 1001:1001, and stores SQLite data in /app/data. Unsuffixed tags such as 2.9.20 stay on Alpine. Production images contain the compiled server and required system libraries; development dependencies and a separate Bun installation stay out of the image. The built-in health check uses /app/bunqueue healthcheck, including on distroless. See the deployment guide for custom probes.

Quickstart

Your first job in about a minute. On Bun the queue runs inside your app, with no server to start:

bun add bunqueue

// jobs.ts
import { Queue, Worker } from 'bunqueue/client';

const queue = new Queue<{ to: string }>('emails', { embedded: true });

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

worker.on('error', (error) => console.error(error));
await queue.add('welcome', { to: 'hello@example.com' });

```bash bun jobs.ts

Processing: hello@example.com

```

That's it: no Redis, no config, no setup. The worker keeps waiting for more jobs until you stop it with Ctrl+C. The example keeps jobs in memory; pass dataPath: './jobs.db' to the queue and the worker to persist them in one SQLite file. msgpackr is the only runtime dependency; cron, SQLite, S3, HTTP and WebSocket use Bun's built-ins.

Processing: hello@example.com

Deno, Python, PHP, Go, Rust and Elixir take the same three steps: see the
[Quick Start](https://bunqueue.dev/guide/quickstart/) for each language.

For multiple active brokers, the repository includes a topology pinned to
PostgreSQL 18.6:

It starts two brokers against one database/namespace. PostgreSQL is server-only; embedded mode keeps using memory/SQLite. Supply both Compose values when the password changes, percent-encoding reserved characters in the URL only. MySQL is not supported. CI validates PostgreSQL 15, 16, 17, and the pinned/recommended 18.6 release. See the storage guide.

One Queue, Any Language (SDKs)

The server does all the heavy lifting. Official client SDKs share the protocol-conformant core Queue, Worker, and Flow surface, so producers and workers can live anywhere in your stack — add a job from TypeScript, process it from Python. Language-specific capabilities are tracked in the SDK guide.

// Node.js / Deno / Cloudflare Workers
import { Queue, Worker } from 'bunqueue-client';

const queue = new Queue('emails', { connection: { host: 'localhost', port: 6789 } });
await queue.add('welcome', { to: 'user@example.com' });

new Worker('emails', async (job) => ({ sent: true }), { concurrency: 10 });

```python

Atomic flows, in every SDK

Every official FlowProducer resolves all job IDs and reciprocal dependency edges locally, then sends one PUSHF command. The broker validates the complete graph and commits it atomically, so a worker cannot observe a leaf from a partially-created flow.

import { FlowProducer } from 'bunqueue-client';

const flows = new FlowProducer({ connection: { host: 'localhost', port: 6789 } });
const root = await flows.add({
  name: 'publish-release',
  queueName: 'release',
  data: { version: 'candidate-42' },
  children: [
    { name: 'unit-tests', queueName: 'checks', data: { suite: 'unit' } },
    { name: 'sdk-tests', queueName: 'checks', data: { suite: 'sdk' } },
  ],
});

console.log(
  root.job.id,
  root.children?.map(({ job }) => job.id)
);
await flows.close();

The repository records the contracts and the test strategy beside each implementation:

¹ The TypeScript SDK has no mutation engine. StrykerJS was removed because its dependency graph produced every advisory the weekly audit had to answer for, none of it reachable from the published client; the planners keep their fast-check coverage.

Property campaigns run in the ordinary SDK gate with deterministic replay seeds. Mutation campaigns run separately against the pure planners and snapshot validators. Contributors can reproduce the complete isolated SDK gate with bun run test:sandbox:sdk; language-specific commands live in each SDK README and AGENTS.md.

SDK guide (all six languages) →

Workflow Engine

Multi-step orchestration with saga compensation, branching, parallel steps and human-in-the-loop signals — built on bunqueue, no new infrastructure:

import { Workflow, Engine } from 'bunqueue/workflow';

const orderFlow = new Workflow('order-pipeline')
  .step(
    'reserve-stock',
    async () => {
      await inventory.reserve();
      return { reserved: true };
    },
    {
      compensate: async () => await inventory.release(), // auto-rollback on failure
    }
  )
  .step(
    'charge',
    async () => {
      return { txId: await payments.charge() };
    },
    {
      compensate: async () => await payments.refund(),
    }
  )
  .waitFor('manager-approval', { timeout: 86_400_000 }) // human-in-the-loop
  .step('confirm', async (ctx) => {
    return { txId: (ctx.steps['charge'] as { txId: string }).txId };
  });

const engine = new Engine({ embedded: true });
engine.register(orderFlow);
const run = await engine.start('order-pipeline', { orderId: 'ORD-1' });
await engine.signal(run.id, 'manager-approval', { approved: true });

Also included: nested workflows, doUntil/doWhile loops, forEach over dynamic lists, schema validation (Zod, ArkType, Valibot or any .parse()), step timeouts, typed events, SQLite-persisted execution state.

Workflow Engine guide →