Deploy to Vercel

Deploy Umami to Vercel’s serverless platform for automatic scaling and global CDN distribution.

Prerequisites

Important: Vercel deployment requires an external PostgreSQL database. Vercel doesn’t provide a built-in database, so you’ll need to use a service like:

Supabase (recommended, free tier available)
Neon (serverless PostgreSQL)
Railway (PostgreSQL only)
AWS RDS
Self-hosted PostgreSQL

Vercel is a serverless platform optimized for Next.js applications. It provides:

Automatic deployments from Git
Global CDN
Automatic HTTPS
Environment variable management
Free tier for hobby projects

Quick Deploy

Set Up PostgreSQL Database

Before deploying to Vercel, create a PostgreSQL database:

Supabase (Recommended)
Neon
Railway PostgreSQL

Go to supabase.com
Create a free account
Create a new project
Wait for database provisioning
Go to Settings → Database
Copy the Connection String (URI format)

Format:

postgresql://postgres:[PASSWORD]@db.[PROJECT].supabase.co:5432/postgres

Go to neon.tech
Sign up for free account
Create a new project
Copy the connection string

Format:

postgresql://user:[email protected]/dbname

Go to railway.app
Create new project
Add PostgreSQL database
Go to Variables tab
Copy DATABASE_URL

Fork the Repository

Fork Umami to your GitHub account:

Go to github.com/umami-software/umami
Click Fork button
Choose your account

Deploy to Vercel

Deploy Button
Manual Import
Vercel CLI

If available, use the Vercel deploy button in the README, or:

Go to vercel.com/new
Import your forked repository
Click Import

Install Vercel CLI:

npm install -g vercel

Deploy from local:

git clone https://github.com/your-username/umami.git
cd umami
vercel

Configure Environment Variables

Add environment variables in Vercel:

In the import screen, expand Environment Variables
Add the following:

DATABASE_URL=your-postgresql-connection-string
APP_SECRET=your-random-secret-string

Generate a secure random string for APP_SECRET:

openssl rand -base64 32

Make sure to add variables for all environments:

Production
Preview
Development (optional)

Deploy

Click Deploy
Vercel will build and deploy Umami
Wait for deployment to complete (2-5 minutes)
Click Visit to open your Umami instance

Initialize Database

On first deployment, you need to initialize the database:

Automatic (Recommended)
Manual Migration

The build process should automatically create tables:

Check deployment logs for database migration
If successful, tables are created automatically

If automatic migration fails:

# Clone your repository locally
git clone https://github.com/your-username/umami.git
cd umami

# Install dependencies
pnpm install

# Set DATABASE_URL
export DATABASE_URL="your-connection-string"

# Run migration
pnpm prisma migrate deploy

Access Umami

Your Umami instance is now live at:

https://your-project.vercel.app

Username: admin
Password: umami

Change the default password immediately!

Custom Domain Setup

Add your own domain to Vercel:

Add Domain in Vercel

Go to your project in Vercel
Click Settings tab
Click Domains in sidebar
Enter your domain (e.g., analytics.yourdomain.com)
Click Add

Configure DNS

Vercel will show you DNS records to add:

Subdomain (CNAME)
Root Domain (A)

For subdomains like analytics.yourdomain.com:

Type: CNAME
Name: analytics
Value: cname.vercel-dns.com
TTL: 3600

For root domains like yourdomain.com:

Type: A
Name: @
Value: 76.76.21.21
TTL: 3600

Verify Domain

Wait for DNS propagation (5 minutes - 48 hours)
Vercel automatically verifies and provisions SSL
Access your Umami at https://your-domain.com

Environment Variables

Configure Umami on Vercel:

Required Variables

# PostgreSQL connection (required)
DATABASE_URL=postgresql://user:password@host:5432/database

# Encryption secret (required)
APP_SECRET=random-secret-string-here

Optional Variables

# Disable Next.js telemetry
NEXT_TELEMETRY_DISABLED=1

# Custom base path
BASE_PATH=/analytics

# Custom tracker script name
TRACKER_SCRIPT_NAME=umami.js,analytics.js

# Force SSL
FORCE_SSL=1

# Allowed frame ancestors (for embedding)
ALLOWED_FRAME_URLS=https://yourdomain.com

# CORS settings
CORS_MAX_AGE=86400

Update Environment Variables

Go to Settings → Environment Variables
Click Edit on the variable
Update the value
Click Save
Redeploy for changes to take effect

Database Configuration

Connection Pooling

Vercel serverless functions create many database connections. Use connection pooling to avoid “too many connections” errors.

Supabase
Neon
PgBouncer

Use the connection pooling endpoint:

# Instead of direct connection:
# postgresql://postgres:[PASSWORD]@db.xxx.supabase.co:5432/postgres

# Use pooler (port 6543):
DATABASE_URL=postgresql://postgres:[PASSWORD]@db.xxx.supabase.co:6543/postgres?pgbouncer=true

Neon automatically handles connection pooling:

DATABASE_URL=postgresql://user:[email protected]/dbname

Set up PgBouncer for your PostgreSQL:

# Connect through PgBouncer
DATABASE_URL=postgresql://user:password@pgbouncer-host:6432/database

Database Performance

Vercel’s free tier has limitations:

100GB bandwidth/month
100 hours serverless function execution
6,000 serverless function invocations per day

High-traffic sites should upgrade to Pro.

Build Configuration

Build Settings

Vercel auto-detects Next.js projects. Default settings:

# Build Command
pnpm run build

# Output Directory
.next

# Install Command
pnpm install

# Development Command
pnpm dev

Custom Build Settings

Override in vercel.json:

vercel.json

{
  "buildCommand": "pnpm run build",
  "devCommand": "pnpm dev",
  "installCommand": "pnpm install",
  "framework": "nextjs",
  "outputDirectory": ".next"
}

Deployment Settings

Auto-Deploy from Git

Vercel automatically deploys:

Production: Pushes to main branch
Preview: Pushes to other branches or pull requests

Every pull request gets a unique preview URL for testing changes.

Disable Auto-Deploy

Go to Settings → Git
Toggle Production Branch or Preview Branches
Click Save

Monitoring and Logs

View Logs

Go to your project dashboard
Click on a deployment
View:
- Build Logs: Compilation output
- Function Logs: Runtime logs
- Error Logs: Runtime errors

Real-time Logs

Use Vercel CLI:

vercel logs your-project.vercel.app

# Follow logs in real-time
vercel logs --follow

Analytics

Enable Vercel Analytics:

Go to Analytics tab
Click Enable Analytics
View:
- Pageviews
- Top pages
- Top referrers
- Device breakdown

Vercel Analytics is separate from Umami. Umami tracks your websites, while Vercel Analytics tracks the Umami dashboard itself.

Troubleshooting

Build fails with database error

The build process needs DATABASE_URL:

Go to Settings → Environment Variables
Ensure DATABASE_URL is set for all environments
Redeploy

If Prisma migration fails:

Run migrations manually (see Initialize Database step)
Check database connection from your local machine

Too many database connections

Enable connection pooling:

Use Supabase pooler (port 6543)
Use Neon (built-in pooling)
Set up PgBouncer
Reduce concurrent function executions

Function timeout errors

Vercel has execution limits:

Hobby: 10 seconds
Pro: 60 seconds
Enterprise: 900 seconds

Solutions:

Upgrade to Pro for longer timeouts
Optimize slow database queries
Use background jobs for long tasks

Deployment stuck or failed

Check deployment logs:

Click on failed deployment
View build logs for errors
Common issues:
- Missing environment variables
- Database connection failed
- Build errors in code
- Out of memory

Try:

Redeploy
Clear build cache: Settings → General → Clear Cache
Check Vercel status page

App is slow

Optimize performance:

Use connection pooling
Add database indexes
Enable Redis caching (if using REDIS_URL)
Upgrade to Pro for better resources
Use ClickHouse for high-volume analytics

Updating Umami

Sync Fork with Upstream

Keep your fork updated:

# Add upstream remote
git remote add upstream https://github.com/umami-software/umami.git

# Fetch updates
git fetch upstream

# Merge updates
git checkout main
git merge upstream/main

# Push to your fork
git push origin main

Auto-Deploy

Vercel automatically deploys when you push to main:

Watch deployment progress in Vercel dashboard
Database migrations run automatically
New version is live when deployment completes

Verify Update

Check the version:

Login to Umami
Go to Settings
Check version number at bottom

Best Practices

Use Connection Pooling

Prevents “too many connections” errors in serverless environment

Enable Preview Deployments

Test changes in preview URLs before merging to production

Set Up Database Backups

Regularly backup your PostgreSQL database

Monitor Function Usage

Track Vercel usage to avoid hitting free tier limits

For high-traffic sites, consider using Railway or self-hosting instead. Vercel’s serverless model can be expensive at scale.

Cost Optimization

Stay within Vercel’s free tier:

Free tier: Unlimited for personal projects with usage limits
Pro: $20/month per member (better limits)
Enterprise: Custom pricing

Tips:

Use efficient database queries
Enable caching where possible
Monitor function execution time
Optimize images and assets
Consider upgrading for high-traffic sites

Next Steps

Add Website

Start tracking your first website

Configure Variables

Set up advanced features

Database Optimization

Optimize PostgreSQL performance

Custom Domain

Set up your own domain

Overview

Installation

Configuration

Vercel Deployment

Deploy to Vercel

Prerequisites

Quick Deploy

Custom Domain Setup

Environment Variables

Update Environment Variables

Database Configuration

Connection Pooling

Database Performance

Build Configuration

Build Settings

Custom Build Settings

Deployment Settings

Auto-Deploy from Git

Disable Auto-Deploy

Monitoring and Logs

View Logs

Real-time Logs

Analytics

Troubleshooting

Updating Umami

Best Practices

Use Connection Pooling

Enable Preview Deployments

Set Up Database Backups

Monitor Function Usage

Cost Optimization

Next Steps

Add Website

Configure Variables

Database Optimization

Custom Domain

Build docs developers (and LLMs) love

Overview

Installation

Configuration

​Deploy to Vercel

​Prerequisites

​Quick Deploy

​Custom Domain Setup

​Environment Variables

​Update Environment Variables

​Database Configuration

​Connection Pooling

​Database Performance

​Build Configuration

​Build Settings

​Custom Build Settings

​Deployment Settings

​Auto-Deploy from Git

​Disable Auto-Deploy

​Monitoring and Logs

​View Logs

​Real-time Logs

​Analytics

​Troubleshooting

​Updating Umami

​Best Practices

Use Connection Pooling

Enable Preview Deployments

Set Up Database Backups

Monitor Function Usage

​Cost Optimization

​Next Steps

Add Website

Configure Variables

Database Optimization

Custom Domain

Build docs developers (and LLMs) love

Deploy to Vercel

Prerequisites

Quick Deploy

Custom Domain Setup

Environment Variables

Update Environment Variables

Database Configuration

Connection Pooling

Database Performance

Build Configuration

Build Settings

Custom Build Settings

Deployment Settings

Auto-Deploy from Git

Disable Auto-Deploy

Monitoring and Logs

View Logs

Real-time Logs

Analytics

Troubleshooting

Updating Umami

Best Practices

Cost Optimization

Next Steps