server · configuration

Server configuration in one typed file.

Configure the whole bunqueue server from a single typed bunqueue.config.ts instead of scattered environment variables. Every option has IntelliSense, every section is optional.

This page is about configuring the standalone server (Server Mode). Embedded mode needs no config file, it takes options directly in the Queue/Worker constructors.

Quick start

Create a bunqueue.config.ts in your project root:

import { defineConfig } from 'bunqueue';

export default defineConfig({
  server: {
    tcpPort: 6789,
    httpPort: 6790,
  },
  storage: {
    dataPath: './data/queue.db',
  },
});

Then start normally:

bunqueue start

The config file is auto-discovered, no flags needed. defineConfig() gives you full TypeScript IntelliSense, so you never have to guess an option name.

Priority order

When the same option is set in more than one place, the first of these wins:

1. CLI flags, bunqueue start --tcp-port 8000
2. Config file, bunqueue.config.ts
3. Environment variables, TCP_PORT=8000
4. Built-in defaults

Use the config file as your baseline and override per environment with env vars or flags.

Picking a config file

bunqueue looks in your project root for bunqueue.config.ts, then bunqueue.config.js, then bunqueue.config.mjs. To use a specific file:

bunqueue start --config ./config/production.config.ts
# Short form
bunqueue start -c ./config/staging.config.ts

Full configuration reference

Every section is optional. Only specify what you need.

server

TCP and HTTP server settings.

defineConfig({
  server: {
    tcpPort: 6789,            // TCP server port (default: 6789)
    httpPort: 6790,           // HTTP/REST API port (default: 6790)
    host: '0.0.0.0',          // Bind address (default: 0.0.0.0)
    tcpSocketPath: undefined, // Reserved, not applied yet: TCP always binds host:port
    httpSocketPath: undefined, // Unix socket for HTTP (overrides host/port)
    tlsCertFile: undefined,   // PEM certificate, enables native TLS on TCP + HTTP (with tlsKeyFile)
    tlsKeyFile: undefined,    // PEM private key (set both or neither, partial config is a startup error)
  },
});

auth

Authentication tokens for clients. Set this on any server reachable from a network.

defineConfig({
  auth: {
    tokens: ['my-secret-token'],    // Auth tokens for TCP/HTTP
    requireAuthForMetrics: false,   // Require auth for /prometheus (env: METRICS_AUTH)
  },
});

Secrets

The config file is code, don’t hardcode secrets that get committed to git. Use process.env.* for sensitive values.

storage

Where jobs persist. Without dataPath, everything is in-memory and lost on restart.

defineConfig({
  storage: {
    dataPath: './data/queue.db',  // SQLite database path (undefined = in-memory)
  },
});

telemetry

Bound labelled Prometheus output independently from the exact global totals:

defineConfig({
  telemetry: {
    maxPrometheusQueues: 100, // 0 disables per-queue label series
  },
});

The environment equivalent is METRICS_MAX_QUEUES. The default is 100; invalid or negative values fall back to the default.

cors

Allowed origins for browser access to the HTTP API.

defineConfig({
  cors: {
    origins: ['https://myapp.com', 'https://admin.myapp.com'],
  },
});

backup

Automatic snapshots of the SQLite database to any S3-compatible storage (AWS, MinIO, Cloudflare R2). See S3 Backup.

defineConfig({
  backup: {
    enabled: true,
    bucket: 'my-bunqueue-backups',
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    sessionToken: process.env.S3_SESSION_TOKEN, // Temporary credentials
    region: 'eu-west-1',              // Default: us-east-1
    endpoint: undefined,              // Custom S3 endpoint (MinIO, R2, etc.)
    virtualHostedStyle: undefined,     // Force bucket-in-host addressing
    interval: 6 * 60 * 60 * 1000,    // Backup interval in ms (default: 6h)
    retention: 7,                     // Backups to keep (default: 7)
    prefix: 'backups/',               // S3 key prefix (default: 'backups/')
  },
});

The server also needs storage.dataPath (or a data-path environment variable); automatic backup is unavailable in in-memory mode.

timeouts

defineConfig({
  timeouts: {
    shutdown: 30000,   // Graceful shutdown timeout in ms (default: 30000)
    stats: 300000,     // Stats logging interval in ms (default: 300000)
    worker: 30000,     // Worker timeout (default: 30000)
    lock: 5000,        // Lock timeout (default: 5000)
  },
});

webhooks

Delivery retries for webhooks.

defineConfig({
  webhooks: {
    maxRetries: 3,       // Max delivery retries (default: 3)
    retryDelay: 1000,    // Retry delay in ms (default: 1000)
  },
});

logging

defineConfig({
  logging: {
    level: 'info',     // 'debug' | 'info' | 'warn' | 'error'
    format: 'json',    // 'text' | 'json'
  },
});

Complete examples

Development

import { defineConfig } from 'bunqueue';

export default defineConfig({
  storage: { dataPath: './data/dev.db' },
  logging: { level: 'debug' },
});

Production

import { defineConfig } from 'bunqueue';

export default defineConfig({
  server: { tcpPort: 6789, httpPort: 6790, host: '0.0.0.0' },
  auth: {
    tokens: [process.env.BUNQUEUE_AUTH_TOKEN!],
    requireAuthForMetrics: true,
  },
  storage: { dataPath: '/data/bunqueue/queue.db' },
  telemetry: { maxPrometheusQueues: 100 },
  cors: { origins: [process.env.FRONTEND_URL!] },
  backup: {
    enabled: true,
    bucket: process.env.S3_BUCKET!,
    accessKeyId: process.env.S3_ACCESS_KEY_ID,
    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    region: 'eu-west-1',
    interval: 3600000,  // Every hour
    retention: 30,
  },
  logging: { level: 'info', format: 'json' },
  timeouts: { shutdown: 60000 },
});

Docker / Kubernetes

Mix the config file (static settings baked into the image) with environment variables (per-deployment values). Remember: when both define the same option, the config file wins.

// bunqueue.config.ts, static settings in the image
import { defineConfig } from 'bunqueue';

export default defineConfig({
  server: { host: '0.0.0.0' },
  logging: { format: 'json' },
  backup: { enabled: true, region: 'eu-west-1' },
});

# Dynamic settings fill what the config file leaves unset
docker run \
  -e TCP_PORT=6789 \
  -e S3_BUCKET=my-bucket \
  -e S3_ACCESS_KEY_ID=xxx \
  -e S3_SECRET_ACCESS_KEY=xxx \
  my-bunqueue-image

Importing defineConfig

Available from both package exports:

import { defineConfig } from 'bunqueue';
// or
import { defineConfig } from 'bunqueue/client';

bunqueue Cloud

Beta Coming Soon

bunqueue Cloud is launching in beta soon. Once the dashboard is live, you’ll connect instances with the cloud section, no code changes needed.

defineConfig({
  cloud: {
    url: 'https://cloud.bunqueue.io',
    apiKey: process.env.BUNQUEUE_CLOUD_API_KEY,
    instanceId: process.env.BUNQUEUE_CLOUD_INSTANCE_ID,
  },
});

Related Guides

• Environment Variables, full env var reference (still supported as fallback)
• Running the Server, server startup guide
• S3 Backup, backup configuration details