Docker/VPS Deployment Guide

For the fastest setup, see the Quick Start.

This guide covers production deployment on a VPS using Docker and Docker Compose.

Prerequisites

Requirements

VPS with at least 2 GB RAM, 2 CPU cores, 20 GB storage, and a supported Linux distribution
Domain name pointed to your VPS IP
SSH access to your VPS

Step-by-Step VPS Setup

1. Prepare Your VPS

Connect to your VPS and install:

Docker Engine: Follow the official guide and the Post installation steps
Node.js v24: Follow the official guide (required for the setup CLI and source installation)

2. Setup and Configure

The easiest way to get started is with the Inbox Zero CLI. You can either use it standalone or from within the cloned repo. Option A: Standalone (no clone needed)

npx @inbox-zero/cli setup

This downloads the Docker Compose file and .env template automatically. Recommended choices for first-time self-hosting:

PostgreSQL/Redis: Docker Compose
Full stack: Yes, everything in Docker (especially when running via standalone npx)

Option B: From the cloned repo

git clone https://github.com/elie222/inbox-zero.git
cd inbox-zero
corepack enable
pnpm install
pnpm run setup

The setup wizard will walk you through configuring Google and/or Microsoft OAuth, choosing an AI provider, and generating secrets. Optional: Automated Google Cloud Setup If you have the gcloud CLI installed, you can automate API enabling and Pub/Sub setup:

npx @inbox-zero/cli setup-google --project-id YOUR_PROJECT_ID --domain yourdomain.com

This works whether or not you have cloned the repository. If you installed the CLI globally, use inbox-zero setup-google with the same flags. The command enables required APIs, creates the Pub/Sub topic and subscription, and guides you through OAuth credential creation. It prints environment variables for you to add to your .env; it does not require a repo checkout. You can also copy .env.example to .env and set the values yourself. If you configure the deployment manually, set:

Google OAuth: GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
LLM Provider: Uncomment one provider block and add your API key
Optional: Microsoft OAuth, external Redis, etc.

For detailed configuration instructions, see the Environment Variables Reference. If you want remote email images to load through a separate privacy-preserving proxy, see the Image Proxy guide. Browser unsubscribe is also optional. Docker Compose and pnpm dev never start apps/unsubscribe-worker. Leave UNSUBSCRIBE_WORKER_URL unset to keep HTTP unsubscribe (one-click POST, then a simple HTML form, then GET). If you do want isolated browser confirmation for JavaScript preference centers, run that app on a dedicated Linux host with gVisor as described in its README, then set UNSUBSCRIBE_WORKER_URL and UNSUBSCRIBE_WORKER_SECRET on the web app. The web app still tries one-click POST and simple HTML forms first. Note: If you only use Microsoft OAuth, set GOOGLE_CLIENT_ID=skipped and GOOGLE_CLIENT_SECRET=skipped. Note: When both the web app and its database/Redis run in Docker, remove or comment out DATABASE_URL, DIRECT_URL, and REDIS_HTTP_URL copied from .env.example. Those example URLs use localhost for running the app on your host; Compose supplies internal Docker hostnames when they are unset. Existing files that still set UPSTASH_REDIS_URL behave the same way. Keep explicit connection URLs when using external services.

3. Deploy

Pull and start the services with your domain:

NEXT_PUBLIC_BASE_URL=https://yourdomain.com docker compose --profile all up -d

The pre-built Docker image is hosted at ghcr.io/elie222/inbox-zero:latest and will be automatically pulled. Important: Compose-time ${...} values are resolved before service-level env_file entries are loaded. If you’re running from a cloned repo, make sure Compose can see the same values as the app by linking or copying apps/web/.env to the repo root as .env. The CLI setup does this automatically for the default configuration and preserves existing user-managed root files. Copied files are refreshed only while their contents match the last CLI-written version; changed copies and retargeted links are preserved with a warning. For manual setup, run ln -s apps/web/.env .env once from the repo root before docker compose up. If a root .env already exists, review it before replacing it, or use docker compose --env-file apps/web/.env --profile all up -d. Shell environment values still take precedence. For named CLI configurations, use the exact Compose command printed by setup. The generated INBOX_ZERO_ENV_FILE setting selects the same named file for container settings. Existing named files created by older CLI versions also need this setting (for example, INBOX_ZERO_ENV_FILE=./apps/web/.env.staging in a cloned repo, or ./.env.staging for a standalone install). Named configs use the same Compose project and do not create isolated deployments.

Using External Database Services (Optional)

The docker-compose.yml supports different deployment modes using profiles:

Profile	Description	Use when
`--profile all`	Includes Postgres and Redis containers	Default, simplest setup
`--profile local-redis`	Local Redis only	Using managed Postgres (RDS, Neon, Supabase)
`--profile local-db`	Local Postgres only	Using managed Redis (Upstash, ElastiCache)
(no profile)	No local databases	Using managed services for both (production recommended)

For external services, set the appropriate environment variables in apps/web/.env:

External Postgres: Set DATABASE_URL and DIRECT_URL
External Redis: Set REDIS_HTTP_URL and REDIS_HTTP_TOKEN. UPSTASH_REDIS_URL and UPSTASH_REDIS_TOKEN still work.

4. Check Logs

Wait for the containers to start:

# Check that containers are running (STATUS should show "Up")
docker ps
# Check logs. This can take 30 seconds to complete
docker logs inbox-zero-services-web-1 -f

5. Access Your Application

Your application should now be accessible at:

http://your-server-ip:3000 (if accessing directly)
https://yourdomain.com (if you’ve set up a reverse proxy with SSL)

Note: For production deployments, you should set up a reverse proxy (like Nginx, Caddy, or use a cloud load balancer) to handle SSL/TLS termination and route traffic to your Docker container.

Scheduled Tasks

The Docker Compose setup includes a cron container that handles these scheduled tasks automatically. It runs interval loops rather than a system cron daemon, so the first request is sent when the container starts and subsequent requests use the intervals below.

Task	Interval	Endpoint	Description
Scheduled mail actions	Every 15 minutes	`/api/cron/scheduled-actions`	Executes delayed actions when QStash is not configured, and restores snoozed threads
Automation jobs	Every 15 minutes	`/api/cron/automation-jobs`	Processes due automation jobs
Email digests	Every 30 minutes	`/api/resend/digest/all`	Sends due email digests
Email watch renewal	Every 6 hours	`/api/watch/all`	Renews Gmail/Outlook push notification subscriptions
Meeting briefs	Every 15 minutes	`/api/meeting-briefs`	Sends pre-meeting briefings to users with the feature enabled
Meeting recorder scheduling	Every 5 minutes	`/api/meeting-recorder/schedule`	Schedules Recall.ai meeting bots when Meeting Recorder is configured
Follow-up reminders	Every hour	`/api/follow-up-reminders`	Processes follow-up reminder notifications

The bundled Compose service does not run the two daily cleanup endpoints. Schedule /api/cron/reasoning-retention when REASONING_RETENTION_DAYS or DRAFT_SENT_TEXT_RETENTION_DAYS is configured. Schedule /api/cron/draft-cleanup when users enable automatic cleanup of unused AI-generated drafts. If you’re not using Docker Compose you need to set up cron jobs manually:

# Scheduled actions (without QStash) and snooze fallback (always) - every 15 minutes
*/15 * * * * curl -s -X GET "https://yourdomain.com/api/cron/scheduled-actions" -H "Authorization: Bearer YOUR_CRON_SECRET"

# Automation jobs - every 15 minutes
*/15 * * * * curl -s -X GET "https://yourdomain.com/api/cron/automation-jobs" -H "Authorization: Bearer YOUR_CRON_SECRET"

# Email digests - every 30 minutes (optional, only if using digests)
*/30 * * * * curl -s -X GET "https://yourdomain.com/api/resend/digest/all" -H "Authorization: Bearer YOUR_CRON_SECRET"

# Reasoning retention - daily (optional, only if REASONING_RETENTION_DAYS is set)
0 3 * * * curl -s -X GET "https://yourdomain.com/api/cron/reasoning-retention" -H "Authorization: Bearer YOUR_CRON_SECRET"

# Unused AI draft cleanup - daily (optional, only if users enable automatic draft cleanup)
0 4 * * * curl -s -X GET "https://yourdomain.com/api/cron/draft-cleanup" -H "Authorization: Bearer YOUR_CRON_SECRET"

# Email watch renewal - every 6 hours
0 */6 * * * curl -s -X GET "https://yourdomain.com/api/watch/all" -H "Authorization: Bearer YOUR_CRON_SECRET"

# Meeting briefs - every 15 minutes (optional, only if using meeting briefs feature)
*/15 * * * * curl -s -X GET "https://yourdomain.com/api/meeting-briefs" -H "Authorization: Bearer YOUR_CRON_SECRET"

# Meeting recorder scheduling - every 5 minutes (optional, only if using Meeting Recorder)
*/5 * * * * curl -s -X GET "https://yourdomain.com/api/meeting-recorder/schedule" -H "Authorization: Bearer YOUR_CRON_SECRET"

# Follow-up reminders - every hour (optional, only if using follow-up reminders feature)
0 * * * * curl -s -X GET "https://yourdomain.com/api/follow-up-reminders" -H "Authorization: Bearer YOUR_CRON_SECRET"

Replace YOUR_CRON_SECRET with the value of CRON_SECRET from your .env file.

These endpoints accept the secret as a GET header (Authorization: Bearer YOUR_CRON_SECRET, as above) or in a POST JSON body ({ "CRON_SECRET": "YOUR_CRON_SECRET" }).

Optional: Background Job Backends

Inbox Zero supports multiple background job backends for self-hosted deployments:

QStash: best when you want a managed queue and are already using Upstash.
BullMQ worker: best when you’re running Docker or another long-lived environment and want a local durable queue backed by Redis.
Internal fallback: no extra services, but limited durability and throttling.

When neither QStash nor BullMQ is configured, we fall back to internal API calls and cron for scheduled actions. This works without extra infrastructure, but lacks built-in retries, deduping, and queue-level backpressure. Features that benefit from QStash:

Feature	Without QStash	With QStash
Email digest	✅ Works (sync, no retries)	✅ Full support
Delayed/scheduled email actions	✅ Works via cron fallback	✅ Full support
AI categorization of senders*	✅ Works (sync)	✅ Works (async with retries)
Bulk inbox cleaning*	✅ Works (sync, no throttling)	✅ Full support

*Early access features - available on the Early Access page.

Option 1: QStash

Cost: QStash has a generous free tier and scales to zero when not in use. See QStash pricing. Add your QStash credentials to .env:

QUEUE_BACKEND=qstash
QSTASH_TOKEN=your-qstash-token
QSTASH_CURRENT_SIGNING_KEY=your-signing-key
QSTASH_NEXT_SIGNING_KEY=your-next-signing-key

Option 2: BullMQ Worker

If you’re already running Docker Compose with Redis, you can use the built-in worker service instead of QStash:

QUEUE_BACKEND=bullmq
REDIS_URL=redis://redis:6379

Then start the worker profile:

docker compose --profile queue-worker up -d

This runs a separate worker process that pulls jobs from Redis and forwards them to the web app over the internal network. By default the worker subscribes to the built-in queues. If you need to tune which queues it listens to, or adjust concurrency, you can override WORKER_QUEUES in your environment.

Building from Source (Optional)

If you prefer to build the image yourself instead of using the pre-built one:

# Clone the repository
git clone https://github.com/elie222/inbox-zero.git
cd inbox-zero

# Install dependencies and configure environment (auto-generates secrets)
corepack enable
pnpm install
pnpm run setup
nano apps/web/.env

# Build and start
docker compose build
NEXT_PUBLIC_BASE_URL=https://yourdomain.com docker compose --profile all up -d

Note: Building from source requires significantly more resources (4GB+ RAM recommended) and takes longer than pulling the pre-built image. Having issues? See the Troubleshooting page for solutions to common problems.

Auto-Join Organization

For self-hosted instances where all users should belong to a single organization, set:

AUTO_JOIN_ORGANIZATION_ENABLED=true

New users will automatically join the organization when they sign in. This requires exactly one organization to exist — create one first via the app before enabling this. To retroactively add all existing users to your organization, run this SQL query:

INSERT INTO "Member" ("id", "emailAccountId", "organizationId", "role", "createdAt")
SELECT gen_random_uuid(), ea.id, '<YOUR_ORG_ID>', 'member', now()
FROM "EmailAccount" ea
WHERE NOT EXISTS (
  SELECT 1 FROM "Member" m WHERE m."emailAccountId" = ea.id
)
ON CONFLICT ("emailAccountId") DO NOTHING;

Replace <YOUR_ORG_ID> with your organization’s ID from the Organization table. If you want newly created organization members to start with organization analytics enabled, set:

AUTO_ENABLE_ORG_ANALYTICS=true

This only affects new memberships created after the setting is enabled. Existing members keep their current stored value.

Quick Start

Setup Guides

Self-Hosting

AWS Deployment

GCP Deployment

Contributing

Integrations

API

Prerequisites

Requirements

Step-by-Step VPS Setup

1. Prepare Your VPS

2. Setup and Configure

3. Deploy

Using External Database Services (Optional)

4. Check Logs

5. Access Your Application

Scheduled Tasks

Optional: Background Job Backends

Option 1: QStash

Option 2: BullMQ Worker

Building from Source (Optional)

Auto-Join Organization

​Prerequisites

​Requirements

​Step-by-Step VPS Setup

​1. Prepare Your VPS

​2. Setup and Configure

​3. Deploy

​Using External Database Services (Optional)

​4. Check Logs

​5. Access Your Application

​Scheduled Tasks

​Optional: Background Job Backends

​Option 1: QStash

​Option 2: BullMQ Worker

​Building from Source (Optional)

​Auto-Join Organization

​Default Organization Analytics Consent

Prerequisites

Requirements

Step-by-Step VPS Setup

1. Prepare Your VPS

2. Setup and Configure

3. Deploy

Using External Database Services (Optional)

4. Check Logs

5. Access Your Application

Scheduled Tasks

Optional: Background Job Backends

Option 1: QStash

Option 2: BullMQ Worker

Building from Source (Optional)

Auto-Join Organization

Default Organization Analytics Consent