Docker

Run Leanbox as a standalone Docker container with an external Postgres database.

Run Leanbox as a standalone Docker container with an external database. Ideal for container platforms like AWS ECS, Google Cloud Run, Fly.io, or Azure Container Instances.

Prerequisites

Before starting, ensure you have:

Docker 20.10 or later installed
A PostgreSQL 14+ database accessible from your Docker host
An Anthropic API key for the AI triage
At least 1GB of available RAM
(Optional) SMTP credentials, if you want to enable the daily email digest

Verify Docker is installed:

docker --version

Pulling the Docker Image

The Leanbox image is available on DockerHub:

docker pull tundekozy/leanbox

Available Tags

Tag	Description
`latest`	Latest stable release
`x.y.z`	Specific version (e.g. `1.2.0`)

Pin to a specific version tag in production to avoid unexpected updates.

Variable	Description
`DATABASE_URL`	PostgreSQL connection string (e.g. `postgresql://user:password@host:5432/leanbox`)
`BETTER_AUTH_SECRET`	Secret key for session encryption. Generate with `openssl rand -hex 32`
`APP_URL`	Public URL where Leanbox is accessible (e.g. `https://leanbox.example.com`)
`ENCRYPTION_KEY`	32-byte hex key used to encrypt stored OAuth tokens. Generate with `openssl rand -hex 32`
`ANTHROPIC_API_KEY`	Anthropic API key that powers the AI triage agent
`REDIS_URL`	Redis connection string for the background queue (e.g. `redis://host:6379`)

Google and Instagram OAuth credentials are not environment variables. Each user provides their own client ID and secret through the in-app connector dialogs, and Leanbox stores them encrypted in the database.

SMTP Configuration

SMTP is only required if you want to enable the daily email digest, which emails users a summary of their triaged inbox. If you leave these unset, Leanbox still runs, the digest just won't be delivered.

Variable	Description
`SMTP_HOST`	SMTP server hostname
`SMTP_PORT`	SMTP server port (usually `587` or `465`)
`SMTP_USER`	SMTP username
`SMTP_PASS`	SMTP password
`SMTP_FROM`	Sender address for the digest (e.g. `Leanbox <noreply@example.com>`)

Running with Docker

Create an .env file with your configuration:

DATABASE_URL=postgresql://user:password@db-host:5432/leanbox
BETTER_AUTH_SECRET=your-better-auth-secret
APP_URL=https://leanbox.example.com
ENCRYPTION_KEY=your-32-byte-hex-encryption-key
ANTHROPIC_API_KEY=sk-ant-...
REDIS_URL=redis://redis-host:6379
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
SMTP_FROM=Leanbox <noreply@example.com>

Run with the environment file:

docker run -d \
  --name leanbox \
  -p 3000:3000 \
  --env-file .env \
  tundekozy/leanbox:latest

Keep your encryption key safe

ENCRYPTION_KEY is used to encrypt every stored OAuth token. If you lose it, all existing Gmail and Instagram connections will become unreadable and users will need to reconnect. Back it up alongside your database credentials.

Database Migrations

Database migrations run automatically every time the container starts, so there's nothing to invoke manually. The migration runner connects to DATABASE_URL, applies any pending migrations, and then boots the Next.js server.

Back up before upgrading

Always back up your Postgres database before pulling a new image. While migrations are designed to be forward-compatible, a recoverable snapshot is the easiest safety net.

Updating the Container

To update Leanbox to a new version:

Pull the new image:
```
docker pull tundekozy/leanbox:latest
```
Stop and remove the existing container:
```
docker stop leanbox
docker rm leanbox
```

Start a new container with the same configuration:

docker run -d \
  --name leanbox \
  -p 3000:3000 \
  --env-file .env \
  tundekozy/leanbox:latest

Persistence

The Leanbox container is stateless. All persistent data (users, sessions, OAuth tokens, triage chats, digests, and drafts) lives in your PostgreSQL database. The Redis instance only holds transient queue jobs and can be restarted without data loss.