Skip to main content
Vercel provides a quick and easy deployment option for LobeHub with automatic HTTPS, CDN, and serverless scaling. This guide covers one-click deployment and manual configuration.

​
Quick deploy

1

Click deploy button

Deploy with VercelThis will fork the repository to your GitHub account and deploy it to Vercel.
2

Configure environment variables

During deployment, you’ll be prompted to set:Required:Recommended:
  • DATABASE_URL - PostgreSQL connection string
  • KEY_VAULTS_SECRET - Encryption key for sensitive data
  • AUTH_SECRET - Secret for authentication (auto-generated if not set)
3

Deploy

Click Deploy and wait for the build to complete (usually 2-3 minutes).
4

Access your deployment

Your LobeHub instance will be available at: https://your-project-name.vercel.app

​
Prerequisites

​
Required external services

Vercel is a serverless platform and cannot run databases. You must use external services for:
Choose a managed PostgreSQL provider:Recommended options:Get your DATABASE_URL in the format:
postgresql://user:password@host:5432/database?sslmode=require
Required if you want file upload and knowledge base features:Recommended options:Configure S3 environment variables:
S3_ENDPOINT=https://...
S3_BUCKET=my-bucket
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_REGION=auto  # for Cloudflare R2
See Storage Configuration for details.

​
Environment variables

​
Configure in Vercel dashboard

  1. Go to your project in Vercel Dashboard
  2. Navigate to Settings → Environment Variables
  3. Add the required variables:

​
Essential variables

# AI Provider (at least one required)
OPENAI_API_KEY=sk-xxxxxx

# Database (required for production)
DATABASE_URL=postgresql://user:password@host:5432/lobechat

# Security (required)
KEY_VAULTS_SECRET=base64-encoded-32-byte-key
AUTH_SECRET=random-secret-string

# Redis (optional but recommended)
REDIS_URL=redis://default:password@host:port

# S3 Storage (for file uploads)
S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET=my-lobehub-bucket
S3_ACCESS_KEY_ID=AKIAXXXXXXXX
S3_SECRET_ACCESS_KEY=xxxxxxxx
S3_REGION=us-east-1
See Environment Variables for the complete list.

​
Generate secure secrets

# Generate a random 32-byte key and base64 encode it
openssl rand -base64 32

​
Custom domain

1

Add domain in Vercel

  1. Go to Settings → Domains
  2. Click Add Domain
  3. Enter your domain (e.g., lobehub.example.com)
2

Configure DNS

Add the DNS records provided by Vercel:For subdomain (e.g., lobehub.example.com):
CNAME  lobehub  cname.vercel-dns.com
For apex domain (e.g., example.com):
A      @        76.76.21.21
3

Wait for SSL

Vercel automatically provisions an SSL certificate. This usually takes a few minutes.

​
Limitations

Be aware of these Vercel platform limitations:

​
Serverless function timeout

  • Hobby plan: 10 seconds
  • Pro plan: 60 seconds
  • Enterprise: 900 seconds
Impact: Long-running AI requests may timeout on Hobby plan. Workaround: Use streaming responses (enabled by default) to keep connections alive.

​
No WebSocket support

Vercel serverless functions don’t support persistent WebSocket connections. Impact: Real-time features use Server-Sent Events (SSE) instead.

​
Cold starts

Serverless functions may experience cold starts after periods of inactivity. Impact: First request after idle period may be slower (1-3 seconds).

​
File size limits

  • Deployment size: 250 MB (compressed)
  • Function size: 50 MB
Impact: Large dependencies may need optimization.

​
Deployment workflow

​
Automatic deployments

By default, Vercel automatically deploys:
  • Production: Every push to main branch
  • Preview: Every push to other branches and PRs

​
Manual deployments

  1. Go to Vercel Dashboard
  2. Select your project
  3. Click Deployments
  4. Click Redeploy on any previous deployment

​
Deploy via CLI

npm i -g vercel

​
Keeping updated

​
Enable auto-sync from upstream

If you used the one-click deploy, Vercel creates a new repository instead of forking. This prevents automatic updates.
To enable updates:
1

Delete current deployment

Remove the project from Vercel dashboard (settings → delete project).
2

Fork the repository

Manually fork lobehub/lobe-chat on GitHub.
3

Import to Vercel

  1. Go to Vercel Dashboard
  2. Click Add New → Project
  3. Import your forked repository
  4. Configure environment variables
  5. Deploy
4

Enable GitHub Actions

In your fork, go to Actions tab and enable:
  • upstream-sync workflow (syncs from original repo)
Disable other workflows to prevent unnecessary runs.
5

Sync updates

The upstream-sync action automatically checks for updates daily.Manual sync:
  1. Go to Actions tab
  2. Select Upstream Sync workflow
  3. Click Run workflow

​
Database migrations

LobeHub automatically runs database migrations on deployment.
If migrations fail:
  1. Check deployment logs in Vercel dashboard
  2. Verify DATABASE_URL is correct
  3. Ensure database is accessible (check IP allowlist)
  4. Run migrations manually:
# Install dependencies
npm install

# Set DATABASE_URL
export DATABASE_URL="postgresql://..."

# Run migrations
npm run db:migrate

​
Troubleshooting

Check build logs in Vercel dashboard:
  1. Go to Deployments
  2. Click on failed deployment
  3. Check Build Logs
Common issues:
  • Missing environment variables
  • TypeScript errors
  • Out of memory (increase Node memory: NODE_OPTIONS=--max-old-space-size=4096)
If requests timeout on Hobby plan:
  1. Upgrade to Pro plan for 60s timeout
  2. Use faster AI models (e.g., GPT-3.5 instead of GPT-4)
  3. Reduce max tokens in responses
  4. Enable streaming (default)
Verify connection:
  1. Check DATABASE_URL format
  2. Ensure ?sslmode=require is appended for managed databases
  3. Check database IP allowlist (allow Vercel IPs or use 0.0.0.0/0)
  4. Test connection locally:
psql "$DATABASE_URL"
Common causes:
  1. Function timeout (see above)
  2. Out of memory
  3. Database connection pool exhausted
Solutions:
  • Use connection pooler (PgBouncer)
  • Reduce concurrent connections
  • Check database logs
After changing environment variables:
  1. Go to Deployments
  2. Click Redeploy (three dots menu)
  3. Select Use existing Build Cache: No

​
Cost optimization

​
Vercel pricing

  • Hobby: Free, 100 GB-hours/month
  • Pro: $20/month, unlimited bandwidth
  • Enterprise: Custom pricing

​
Reduce costs

  1. Use external caching - Upstash Redis reduces function invocations
  2. Optimize images - Use Vercel Image Optimization
  3. CDN caching - Configure Cache-Control headers
  4. Function regions - Deploy to regions close to users

​
Database costs

  • Neon: Free tier with 0.5 GB storage
  • Supabase: Free tier with 500 MB database
  • Vercel Postgres: Starts at $10/month

​
Next steps

Environment variables

Complete environment variable reference

Authentication

Set up SSO and user management

Database

Configure PostgreSQL and run migrations

Storage

Set up S3 for file uploads

Build docs developers (and LLMs) love

Get started for freeTalk to us