Task Queue

Bunship's AI generation pipeline uses a pluggable task queue with two backends. The system auto-detects which backend to use based on the environment variables you provide.

Backend Comparison

Auto-Detection

The adapter is selected by the first matching environment variable:

TRIGGER_SECRET_KEY  ->  Web/API runtime uses the Trigger.dev adapter (highest priority)
REDIS_URL           ->  Web/API or standalone API runtime uses BullMQ
(fallback)          ->  BullMQ

No code changes needed. Set the right env var for your deployment.

Option A: Trigger.dev (Recommended for Vercel)

Best for Vercel deployments. Tasks run on Trigger.dev's cloud infrastructure.

Setup

1. Create account at cloud.trigger.dev
2. Create a project, note your Project ID and the Secret Key used by Web/API to enqueue runs
3. Confirm the SDK and CLI versions match. The current repo pins them in apps/ship-api/package.json at 4.4.6:

@trigger.dev/sdk=4.4.6
@trigger.dev/build=4.4.6
trigger.dev CLI=4.4.6

4. Add dispatch variables to the Web/API container runtime:

TRIGGER_SECRET_KEY=sk_dev_your_key_here
TRIGGER_PROJECT_ID=your_project_id

TRIGGER_SECRET_KEY lets the app enqueue runs on Trigger.dev. It is not a Docker build variable and it is not required in Trigger cloud task runtime.

Local Development

# Terminal 1: Start Trigger.dev local dev worker
cd apps/ship-api
bun run trigger:dev

# Terminal 2: Start your app
bun run dev

Deploy Tasks

Manual deploy:

cd apps/ship-api
bun run trigger:deploy

This registers ai-generate and the ai-stale-recovery schedule on Trigger.dev.

CI/CD Deploy (GitHub Actions)

A workflow at .github/workflows/deploy-trigger.yml automatically deploys tasks when you push changes to main.

Triggers:

• Push to main that modifies Trigger task directories, apps/ship-api/package.json, trigger.config.ts, or the workflow
• Manual dispatch from the Actions tab

Required GitHub Secrets / Variables:

For forked repos: Fork users set their own TRIGGER_ACCESS_TOKEN and TRIGGER_PROJECT_ID in their repo's Settings → Secrets. The workflow deploys to their own Trigger.dev project — no conflict with the upstream repo.

Keep Trigger-Related Env Separate

Production Env Vars (Trigger.dev Cloud Task Runtime)

After deployment, tasks run on Trigger.dev cloud. Configure these in Trigger.dev project Environment Variables for prod:

Provider-specific vars (only for enabled providers):

Optional tuning vars:

Option B: BullMQ

Best for self-hosted deployments with a persistent server (Railway, Fly.io, VPS).

Requirements

• Redis instance (Upstash, Railway Redis, or self-hosted)
• Persistent process (not serverless)

Setup

1. Ensure REDIS_URL is set and no TRIGGER_SECRET_KEY is present:

REDIS_URL=redis://your-redis-url:6379

2. Deploy ship-api as a standalone server:

cd apps/ship-api
bun run src/index.ts

The BullMQ worker starts automatically with admission control, retries, and stale-task scanning.

Stale Task Recovery

Regardless of backend, Bunship includes a safety net that automatically fails stuck tasks and refunds credits.

Code Map

apps/ship-api/src/services/ai/queue/
├── types.ts              # TaskQueueAdapter interface
├── processor.ts          # Shared execution logic
├── adapter-bullmq.ts     # BullMQ implementation
├── adapter-trigger.ts    # Trigger.dev implementation
└── index.ts              # Auto-detection + adapter export

Next Steps