Bunqueue Production Deployment Guide: Docker, Systemd & PM2

guide · deployment

From laptop to production.

How to run bunqueue in production as the single-instance job queue it is designed to be. Docker, systemd and PM2 setups, S3 backups, health checks, resource limits and disaster recovery.

1M jobs validated, 100% integrity3 deployment optionsS3 backups for disaster recovery1 process, no clustering

Caution

bunqueue runs as a single process. There’s no built-in clustering or multi-node support. Tested and validated up to 1 million jobs with 100% data integrity.

Architecture Overview

Your Application

Web App

API

Workers

↓

bunqueue embedded mode, single instance

↓

SQLite Database ./data/bunq.db, local file

↓

S3 Backup optional, disaster recovery

Deployment Options

Option 1: Embedded Mode (Recommended)

Run bunqueue directly in your application process. No separate server needed.

Caution

Set DATA_PATH environment variable or use a configuration file for SQLite persistence. Without it, data is stored in-memory only and will be lost on restart.

# Enable SQLite persistence
export DATA_PATH=./data/bunq.db

Config File

Instead of environment variables, you can centralize all settings in a typed bunqueue.config.ts:

import { defineConfig } from 'bunqueue';

export default defineConfig({
  storage: { dataPath: './data/bunq.db' },
  auth: { tokens: [process.env.AUTH_TOKEN!] },
  backup: { enabled: true, bucket: 'my-backups' },
});

See Configuration File for the full reference.

app.ts

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

// Your web framework (Hono, Elysia, Express...)
const app = new Hono();

// Queue is embedded in the same process (uses DATA_PATH for persistence)
const emailQueue = new Queue('emails', { embedded: true });

app.post('/send-email', async (c) => {
  const { to, subject } = await c.req.json();
  await emailQueue.add('send', { to, subject });
  return c.json({ queued: true });
});

// Worker runs in the same process
new Worker('emails', async (job) => {
  await sendEmail(job.data);
  return { sent: true };
}, { embedded: true, concurrency: 5 });

export default app;

Pros:

• Simplest setup
• No network latency
• Single deployment unit

Cons:

• Queue dies if app dies
• Harder to scale workers independently

Option 2: Separate Worker Process (through the server)

Run your API and workers as separate processes. Multi-process setups always go through the bunqueue server: it owns the SQLite file, and every process talks to it over TCP.

# One server owns the database
bunqueue start --data-path ./data/bunq.db

// api.ts - Your web server (TCP client, no embedded flag)
import { Queue } from 'bunqueue/client';

const queue = new Queue('tasks');

app.post('/task', async (c) => {
  await queue.add('process', { data: '...' });
  return c.json({ ok: true });
});

// worker.ts - Separate process (TCP client)
import { Worker } from 'bunqueue/client';

new Worker('tasks', async (job) => {
  // Heavy processing here
  return { done: true };
}, { concurrency: 10 });

console.log('Worker started');

Pros:

• Workers can be restarted and scaled independently
• Better resource isolation

Cons:

• One more process to manage (the server)
• All traffic goes over TCP (localhost round trip)

Never share one SQLite file between two embedded processes

Two processes with embedded: true pointing at the same DATA_PATH do not work. Each process keeps its own in-memory queue state and reads SQLite only once at startup, so a worker process never sees jobs pushed live by the API process, and both run independent cleanup and buffered writes against the same file. If you need more than one process, use the server as shown above.

Option 3: Server Mode (CLI)

Run bunqueue as a standalone server. Interact via CLI or HTTP API.

# Start server
bunqueue start --tcp-port 6789 --http-port 6790

# Add jobs via CLI
bunqueue push emails '{"to": "user@example.com", "subject": "Hello"}'

# Or via HTTP API
curl -X POST http://localhost:6790/queues/emails/jobs \
  -H "Content-Type: application/json" \
  -d '{"data": {"to": "user@example.com"}}'

Tip

The Queue and Worker classes from bunqueue/client connect to the TCP server by default (when embedded is not set to true). You can also use the CLI or HTTP API.

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

// Connects to localhost:6789 by default
const queue = new Queue('emails');
await queue.add('send', { to: 'user@example.com' });

// Worker also connects to the server
const worker = new Worker('emails', async (job) => {
  await sendEmail(job.data);
  return { sent: true };
});

Docker Deployment

Dockerfile

FROM oven/bun:1-alpine

WORKDIR /app

# Copy package files
COPY package.json bun.lock* ./
RUN bun install --frozen-lockfile --production

# Copy application
COPY . .

# Create data directory
RUN mkdir -p /app/data

# Environment
ENV DATA_PATH=/app/data/bunq.db
ENV NODE_ENV=production

# Health check (wget ships with the Alpine base, curl does not)
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget --spider -q http://127.0.0.1:6790/health || exit 1

EXPOSE 6789 6790

CMD ["bun", "run", "start"]

Docker Compose

version: '3.8'

services:
  bunqueue:
    build: .
    ports:
      - "6789:6789"  # TCP
      - "6790:6790"  # HTTP
    volumes:
      - bunqueue-data:/app/data
    environment:
      - DATA_PATH=/app/data/bunq.db
      - AUTH_TOKENS=${AUTH_TOKENS}
      - S3_BACKUP_ENABLED=1
      - S3_ACCESS_KEY_ID=${S3_ACCESS_KEY_ID}
      - S3_SECRET_ACCESS_KEY=${S3_SECRET_ACCESS_KEY}
      - S3_BUCKET=${S3_BUCKET}
      - S3_REGION=${S3_REGION}
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M

volumes:
  bunqueue-data:

Systemd Service

For bare-metal or VM deployments:

/etc/systemd/system/bunqueue.service

[Unit]
Description=bunqueue Job Queue
After=network.target

[Service]
Type=simple
User=bunqueue
Group=bunqueue
WorkingDirectory=/var/lib/bunqueue
ExecStart=/usr/local/bin/bunqueue start
Restart=always
RestartSec=5

# Environment
Environment=NODE_ENV=production
Environment=DATA_PATH=/var/lib/bunq.db
EnvironmentFile=/etc/env

# Security
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/bunqueue

# Resource limits
MemoryMax=512M
CPUQuota=200%

[Install]
WantedBy=multi-user.target

# Install
sudo systemctl daemon-reload
sudo systemctl enable bunqueue
sudo systemctl start bunqueue

# Check status
sudo systemctl status bunqueue
sudo journalctl -u bunqueue -f

Updating bunqueue

To update bunqueue on a systemd-managed server:

# 1. Stop the service
sudo systemctl stop bunqueue

# 2. Update the package
bun install -g bunqueue@latest

# 3. Verify the new version
bunqueue --version

# 4. Restart the service
sudo systemctl start bunqueue

# 5. Confirm the running version
curl http://localhost:6790/health | jq .version

Caution

Always verify the running version with curl /health after restart. Simply running bun update does not restart the service, you must explicitly stop and start it with systemctl.

Building from Source

Compile bunqueue into a standalone executable for production deployment.

Build Command

# Clone the repository
git clone https://github.com/egeominotti/bunqueue.git
cd bunqueue

# Install dependencies
bun install

# Build standalone binary
bun run build

This creates dist/bunqueue (~56 MB), a self-contained executable with no runtime dependencies.

Verify Build

# Check version
./dist/bunqueue --version

# Show help
./dist/bunqueue --help

# Start server
./dist/bunqueue start

Install Globally

# Copy to system path
sudo cp dist/bunqueue /usr/local/bin/

# Verify installation
bunqueue --version

Tip

The compiled binary includes the Bun runtime. No need to install Bun on the target server.

---

PM2 Process Manager

For cross-platform process management with PM2:

Compiled Binary (Recommended)

First, build the standalone executable:

bun run build

Then configure PM2:

ecosystem.config.js

module.exports = {
  apps: [{
    name: 'bunqueue',
    script: '/usr/local/bin/bunqueue',  // Compiled binary
    args: 'start',
    instances: 1,  // Single instance only - no cluster mode
    exec_mode: 'fork',
    autorestart: true,
    watch: false,
    max_memory_restart: '512M',
    env: {
      NODE_ENV: 'production',
      DATA_PATH: '/var/lib/bunq.db',
      TCP_PORT: 6789,
      HTTP_PORT: 6790,
    },
    error_file: '/var/log/error.log',
    out_file: '/var/log/out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    merge_logs: true,
  }]
};

Development Mode (with Bun)

For development or when using the source directly:

ecosystem.config.js

module.exports = {
  apps: [{
    name: 'bunqueue',
    script: 'bun',
    args: 'run start',
    cwd: '/opt/bunqueue',
    instances: 1,
    exec_mode: 'fork',
    autorestart: true,
    max_memory_restart: '512M',
    env: {
      NODE_ENV: 'production',
      DATA_PATH: '/var/lib/bunq.db',
      TCP_PORT: 6789,
      HTTP_PORT: 6790,
    },
  }]
};

PM2 Commands

# Start
pm2 start ecosystem.config.js

# Restart
pm2 restart bunqueue

# Stop
pm2 stop bunqueue

# View logs
pm2 logs bunqueue

# Monitor
pm2 monit

# Save process list for startup
pm2 save
pm2 startup

Caution

Do not use PM2 cluster mode (instances > 1). bunqueue is a single-instance queue and multiple instances will cause data corruption.

Environment Variables

Variable	Description	Default
DATA_PATH	SQLite database path	in-memory
TCP_PORT	TCP server port	6789
HTTP_PORT	HTTP server port	6790
AUTH_TOKENS	Comma-separated auth tokens	-
S3_BACKUP_ENABLED	Enable S3 backups	0
S3_ACCESS_KEY_ID	S3 access key	-
S3_SECRET_ACCESS_KEY	S3 secret key	-
S3_BUCKET	S3 bucket name	-
S3_REGION	S3 region	us-east-1
S3_ENDPOINT	Custom S3 endpoint	-
S3_BACKUP_INTERVAL	Backup interval (ms)	21600000 (6h)
S3_BACKUP_RETENTION	Backups to keep	7

S3 Backup Configuration

Tip

Always enable S3 backups in production. SQLite is a single file, if it corrupts or the disk fails, you lose everything.

AWS S3

S3_BACKUP_ENABLED=1
S3_ACCESS_KEY_ID=AKIA...
S3_SECRET_ACCESS_KEY=...
S3_BUCKET=my-bunqueue-backups
S3_REGION=us-east-1
S3_BACKUP_INTERVAL=3600000  # Every hour
S3_BACKUP_RETENTION=24       # Keep 24 backups

Cloudflare R2

S3_BACKUP_ENABLED=1
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_BUCKET=bunqueue-backups
S3_ENDPOINT=https://ACCOUNT_ID.r2.cloudflarestorage.com
S3_REGION=auto

MinIO (Self-hosted)

S3_BACKUP_ENABLED=1
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_BUCKET=bunqueue
S3_ENDPOINT=http://minio:9000
S3_REGION=us-east-1

Health Checks

bunqueue exposes health endpoints:

# HTTP health check (detailed)
curl http://localhost:6790/health
# {"ok":true,"status":"healthy","uptime":3600,"version":"2.8.30",
#  "queues":{"waiting":5,"active":2},"connections":{"ws":0,"sse":0},
#  "memory":{"heapUsed":45,"heapTotal":64,"rss":128}}

# Simple liveness probe
curl http://localhost:6790/healthz
# OK

# Readiness probe
curl http://localhost:6790/ready
# {"ok":true,"ready":true}

# Queue stats
curl http://localhost:6790/stats
# {"ok":true,"stats":{"waiting":5,"active":2,"completed":1000,"dlq":0}}

# Prometheus metrics (text format)
curl http://localhost:6790/prometheus

Kubernetes Probes

livenessProbe:
  httpGet:
    path: /healthz
    port: 6790
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: 6790
  initialDelaySeconds: 5
  periodSeconds: 5

Resource Requirements

Memory

Workload	Recommended RAM
Light (<1k jobs/day)	128 MB
Medium (1k-10k jobs/day)	256 MB
Heavy (10k-100k jobs/day)	512 MB
Very Heavy (>100k jobs/day)	1 GB+

Disk

SQLite database size depends on:

• Number of jobs retained
• Job data size
• removeOnComplete setting

// Reduce disk usage
new Queue('tasks', {
  defaultJobOptions: {
    removeOnComplete: true,  // Don't keep completed jobs
    removeOnFail: false,     // Keep failed for debugging
  }
});

CPU

bunqueue is I/O bound, not CPU bound. A single core handles most workloads.

Production Checklist

For failure semantics, the crash timeline and the invariants each adversarial test suite proves, see Production Operations.

1. Enable S3 backups

   Don’t skip this. SQLite corruption = data loss.

2. Set auth tokens

   AUTH_TOKENS=token1,token2,token3

3. Use durable: true for critical jobs

   // Payments, orders, and critical events
   await queue.add('payment', data, { durable: true });

4. Configure resource limits

   Prevent runaway memory/CPU usage.

5. Set up monitoring

   Scrape /prometheus with Prometheus or similar.

6. Configure log aggregation

   Send logs to a central system.

7. Test backup restoration

   # List backups first
   bunqueue backup list
   # Then restore by key
   bunqueue backup restore backups/bunq-2026-01-30T12:00:00.db --force

8. Set up alerts

   • DLQ count > threshold
   • Waiting jobs growing
   • Worker not processing

Scaling Limitations

No Clustering

bunqueue does not support horizontal scaling or clustering. It’s a single-instance queue.

What this means

• ❌ No multi-node deployment
• ❌ No automatic failover
• ❌ No distributed processing across machines
• ✅ Multiple workers in same process (concurrency)
• ✅ Multiple worker processes on the same machine (through the TCP server, never by sharing the SQLite file)

When bunqueue is enough

Scenario	Jobs/day	bunqueue?
Small SaaS	<10k	✅ Perfect
Medium app	10k-100k	✅ Fine
Large app	100k-1M	✅ Tested
Enterprise	>1M	⚠️ Test first

When to use something else

If you need:

• High availability → Redis + BullMQ with Sentinel
• Distributed processing → Kafka, RabbitMQ
• Multi-region → Managed queues (SQS, Cloud Tasks)
• Complex workflows → Temporal, Inngest

Vertical scaling

bunqueue scales vertically well:

• More RAM = more jobs in memory
• Faster disk (NVMe) = faster SQLite
• More CPU cores = more worker concurrency

// Scale worker concurrency with available CPUs
import { cpus } from 'os';

new Worker('tasks', processor, {
  concurrency: cpus().length * 2
});

Disaster Recovery

Backup Strategy

Every 1 hour

→

S3 backup

Every 6 hours

→

Verify backup integrity

Every day

→

Test restore in staging

Recovery Steps

1. Stop bunqueue

   systemctl stop bunqueue

2. List available backups

   bunqueue backup list

3. Restore from backup

   bunqueue backup restore backups/bunq-2026-01-30T12:00:00.db --force

4. Start bunqueue

   systemctl start bunqueue

Point-in-Time Recovery

SQLite WAL mode allows recovery to recent states. Stop the server first: copying the database and WAL while bunqueue is writing can produce a torn, unusable copy.

# Stop, then copy both files together
systemctl stop bunqueue
cp data/bunq.db data/bunq.db-wal /backup/
systemctl start bunqueue

# Restore (server stopped)
cp /backup/bunq.db* data/

Security

Network

• Terminate TLS natively with TLS_CERT_FILE and TLS_KEY_FILE (both TCP and HTTP, see Native TLS), or run behind a reverse proxy (nginx, Caddy)
• Firewall TCP/HTTP ports

Authentication

# Generate strong tokens
AUTH_TOKENS=$(openssl rand -hex 32),$(openssl rand -hex 32)

File Permissions

# Restrict database access
chmod 600 /var/lib/bunq.db
chown bunqueue:bunqueue /var/lib/bunq.db

Monitoring with Prometheus

prometheus.yml

scrape_configs:
  - job_name: 'bunqueue'
    static_configs:
      - targets: ['localhost:6790']
    metrics_path: /prometheus

Key Metrics

Metric	Alert Threshold
bunqueue_jobs_waiting	> 1000 for 5 min
bunqueue_jobs_dlq	> 10
bunqueue_jobs_active	0 for 5 min (workers dead?)
bunqueue_jobs_failed_total	increasing rapidly

Example: Full Production Setup

/etc/env

NODE_ENV=production
DATA_PATH=/var/lib/bunq.db
TCP_PORT=6789
HTTP_PORT=6790
AUTH_TOKENS=prod-token-abc123,deploy-token-xyz789

# S3 Backups
S3_BACKUP_ENABLED=1
S3_ACCESS_KEY_ID=AKIA...
S3_SECRET_ACCESS_KEY=...
S3_BUCKET=company-bunqueue-backups
S3_REGION=eu-west-1
S3_BACKUP_INTERVAL=3600000
S3_BACKUP_RETENTION=48

production.ts

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

const queue = new Queue('production-tasks', {
  embedded: true,
  defaultJobOptions: {
    attempts: 5,
    backoff: 5000,
    removeOnComplete: true,
  }
});

// Configure DLQ alerts
queue.setDlqConfig({
  maxEntries: 1000,
  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
});

// Regular jobs (buffered writes - high throughput)
await queue.add('send-email', { to: 'user@example.com' });

// Critical jobs (immediate disk write - no data loss)
await queue.add('process-payment', { orderId: '123' }, { durable: true });

// Worker with production settings
new Worker('production-tasks', async (job) => {
  await job.updateProgress(0, 'Starting...');

  try {
    const result = await processJob(job.data);
    await job.log(`Completed: ${JSON.stringify(result)}`);
    return result;
  } catch (error) {
    await job.log(`Error: ${error.message}`);
    throw error;
  }
}, {
  embedded: true,
  concurrency: 10,
  heartbeatInterval: 5000,
});