Environment Variables

Umami can be configured using environment variables to customize behavior, enable features, and integrate with external services.

Required Variables

These variables are required for Umami to function:

DATABASE_URL

Database Connection

PostgreSQL database connection string.

DATABASE_URL=postgresql://username:password@hostname:port/database

Format:

postgresql://[user]:[password]@[host]:[port]/[database]

Examples:

DATABASE_URL=postgresql://umami:mypassword@localhost:5432/umami

Never commit your DATABASE_URL to version control. Use .env files that are in .gitignore.

APP_SECRET

Application Secret

Random string used for encrypting sessions, tokens, and sensitive data.

APP_SECRET=your-random-secret-string-minimum-32-characters

Generate a secure secret:

openssl rand -base64 32

Critical: Change APP_SECRET before deploying to production. Never use default or example values.

Optional Configuration

Application Settings

PORT

Port number for the application server.

PORT=3000

Default: 3000

Cloud platforms like Railway and Vercel automatically set the PORT variable. You usually don’t need to change this.

HOSTNAME

Hostname for the server to bind to.

HOSTNAME=0.0.0.0

Default: 0.0.0.0 (all interfaces) Options:

0.0.0.0 - Accept connections from any interface
localhost - Only local connections
Specific IP address

BASE_PATH

Serve Umami from a subdirectory.

BASE_PATH=/analytics

Example: Access Umami at https://yourdomain.com/analytics

When using BASE_PATH, you must rebuild the application for changes to take effect.

Tracking Configuration

TRACKER_SCRIPT_NAME

Customize the tracking script filename to avoid ad blockers.

TRACKER_SCRIPT_NAME=custom-script.js

Multiple names:

TRACKER_SCRIPT_NAME=analytics.js,stats.js,umami.js

Benefits:

Avoid ad blocker detection
Use branded script names
Support multiple script names simultaneously

Usage:

<!-- Default -->
<script src="/script.js" data-website-id="..."></script>

<!-- Custom -->
<script src="/analytics.js" data-website-id="..."></script>

TRACKER_SCRIPT_URL

Serve tracking script from external URL.

TRACKER_SCRIPT_URL=https://cdn.yourdomain.com/umami.js

Host the script on your own CDN for better performance and control.

COLLECT_API_ENDPOINT

Customize the data collection endpoint.

COLLECT_API_ENDPOINT=/api/collect

Default: /api/send Use this to:

Avoid ad blocker patterns
Match your API structure
Use custom endpoint names

Security Settings

FORCE_SSL

Force HTTPS and add security headers.

FORCE_SSL=1

When enabled:

Adds Strict-Transport-Security header
Forces HTTPS redirects
Enhances security posture

Only enable this if you have HTTPS properly configured. Enabling without HTTPS will break your site.

ALLOWED_FRAME_URLS

Configure Content Security Policy for embedding Umami in iframes.

ALLOWED_FRAME_URLS=https://yourdomain.com https://app.yourdomain.com

Use cases:

Embed Umami dashboard in your app
Display analytics on your website
Allow specific domains to frame Umami

CORS_MAX_AGE

CORS preflight cache duration in seconds.

CORS_MAX_AGE=86400

Default: 86400 (24 hours)

Cloud Mode

CLOUD_MODE

Enable cloud/SaaS mode features.

CLOUD_MODE=1

Enables:

Multi-tenant features
Team workspaces
Usage limits
Billing integration

Cloud mode is for SaaS deployments. Most self-hosted users don’t need this.

CLOUD_URL

Cloud service URL for remote tracking.

CLOUD_URL=https://cloud.umami.is

Required additional variables when using cloud mode:

CLICKHOUSE_URL=http://clickhouse:8123
REDIS_URL=redis://redis:6379

Database Options

DATABASE_TYPE

Database type (usually auto-detected).

DATABASE_TYPE=postgresql

Options:

postgresql (default and recommended)
mysql (deprecated, not recommended)

Umami v2+ focuses on PostgreSQL. MySQL support is limited and may be removed in future versions.

SKIP_DB_CHECK

Skip database connection check on startup.

SKIP_DB_CHECK=1

Only use this if you know what you’re doing. Skipping DB check can lead to runtime errors.

High-Volume Options

For sites with millions of pageviews:

CLICKHOUSE_URL

ClickHouse database for high-volume analytics.

CLICKHOUSE_URL=http://clickhouse:8123

Benefits:

Handle billions of events
Faster queries on large datasets
Columnar storage for analytics

ClickHouse is optional and only needed for very high-traffic sites (millions of events per day).

REDIS_URL

Redis for caching and session storage.

REDIS_URL=redis://redis:6379

Alternative formats:

# With password
REDIS_URL=redis://:password@redis:6379

# Redis Sentinel
REDIS_URL=redis-sentinel://sentinel:26379/mymaster

# TLS
REDIS_URL=rediss://redis:6380

Benefits:

Faster session management
Improved performance
Distributed caching

Localization

DEFAULT_LOCALE

Default language for the UI.

DEFAULT_LOCALE=en-US

Available locales:

en-US - English (default)
es-ES - Spanish
fr-FR - French
de-DE - German
zh-CN - Chinese (Simplified)
ja-JP - Japanese
ko-KR - Korean
pt-BR - Portuguese (Brazil)
ru-RU - Russian
And many more…

Build-Time Variables

These affect the build process:

NEXT_TELEMETRY_DISABLED

Disable Next.js telemetry.

NEXT_TELEMETRY_DISABLED=1

Disable telemetry for privacy and slightly faster builds.

NODE_ENV

Node.js environment mode.

NODE_ENV=production

Options:

production - Optimized builds, no debug info
development - Debug mode, hot reload
test - Testing environment

Always use NODE_ENV=production for production deployments.

NODE_OPTIONS

Node.js runtime options.

NODE_OPTIONS="--max-old-space-size=4096"

Common options:

# Increase memory limit
NODE_OPTIONS="--max-old-space-size=4096"

# Enable source maps
NODE_OPTIONS="--enable-source-maps"

Setting Environment Variables

Local Development

Create a .env file in the project root:

.env

DATABASE_URL=postgresql://umami:password@localhost:5432/umami
APP_SECRET=your-random-secret-here
NEXT_TELEMETRY_DISABLED=1

The .env file is in .gitignore by default. Never commit it to version control.

Docker Compose

Add to docker-compose.yml:

docker-compose.yml

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      APP_SECRET: replace-me-with-random-string
      TRACKER_SCRIPT_NAME: analytics.js
      FORCE_SSL: 1

Or use an .env file:

docker-compose.yml

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    env_file:
      - .env

Docker Run

Pass variables with -e flag:

docker run -d \
  -e DATABASE_URL=postgresql://user:pass@host:5432/db \
  -e APP_SECRET=my-secret \
  -e TRACKER_SCRIPT_NAME=analytics.js \
  -p 3000:3000 \
  ghcr.io/umami-software/umami:latest

Railway

Go to your Umami service
Click Variables tab
Click + New Variable
Add key and value
Click Add

Railway automatically redeploys when variables change.

Vercel

Go to Settings → Environment Variables
Enter variable name and value
Select environments (Production, Preview, Development)
Click Save
Redeploy for changes to take effect

System Environment

For systemd or process managers:

# Export in shell
export DATABASE_URL=postgresql://...
export APP_SECRET=...
pnpm start

systemd service file

[Service]
Environment="DATABASE_URL=postgresql://..."
Environment="APP_SECRET=..."
ExecStart=/usr/bin/pnpm start

Configuration Examples

Minimal Production Setup

.env

DATABASE_URL=postgresql://umami:password@localhost:5432/umami
APP_SECRET=8f3d9a7b6c2e1f4a9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4e3d2c1b0a9f8e7d6c
NEXT_TELEMETRY_DISABLED=1

Advanced Production

.env

# Database
DATABASE_URL=postgresql://umami:password@localhost:5432/umami

# Security
APP_SECRET=8f3d9a7b6c2e1f4a9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4e3d2c1b0a9f8e7d6c
FORCE_SSL=1

# Tracking
TRACKER_SCRIPT_NAME=analytics.js,stats.js

# UI
DEFAULT_LOCALE=en-US
BASE_PATH=/analytics

# Performance
REDIS_URL=redis://localhost:6379

# Next.js
NEXT_TELEMETRY_DISABLED=1
NODE_ENV=production

High-Volume Setup

.env

# Databases
DATABASE_URL=postgresql://umami:password@localhost:5432/umami
CLICKHOUSE_URL=http://localhost:8123
REDIS_URL=redis://localhost:6379

# Security
APP_SECRET=8f3d9a7b6c2e1f4a9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4e3d2c1b0a9f8e7d6c
FORCE_SSL=1

# Cloud mode
CLOUD_MODE=1
CLOUD_URL=https://analytics.yourdomain.com

# Tracking
TRACKER_SCRIPT_NAME=umami.js
COLLECT_API_ENDPOINT=/api/collect

# Performance
NODE_OPTIONS="--max-old-space-size=4096"

Troubleshooting

Environment variables not loading

Check:

.env file exists in project root
No syntax errors in .env file
Variables don’t have quotes unless needed
Restart the application after changes

Format:

# Correct
DATABASE_URL=postgresql://...

# Incorrect (usually)
DATABASE_URL="postgresql://..."

DATABASE_URL not found

Make sure:

Variable is set before building/starting
No typos in variable name
Connection string format is correct
Using = not : or space

Test:

echo $DATABASE_URL

Changes not taking effect

Rebuild after changing build-time variables (BASE_PATH, TRACKER_SCRIPT_NAME)
Restart after changing runtime variables
Clear Next.js cache: rm -rf .next
In Docker: recreate containers

Invalid APP_SECRET

Requirements:

Minimum 32 characters recommended
Use alphanumeric and special characters
Don’t use spaces
Base64 encoding recommended

Generate:

openssl rand -base64 32

Best Practices

Use Strong Secrets

Generate cryptographically secure random strings for APP_SECRET

Never Commit Secrets

Keep .env in .gitignore and use secret management tools

Document Your Config

Create .env.example with dummy values for team reference

Use Different Secrets

Don’t reuse APP_SECRET across environments or applications

Security Checklist:

APP_SECRET is random and unique
DATABASE_URL uses strong password
Secrets are not committed to Git
Production uses different secrets than development
FORCE_SSL enabled for HTTPS deployments
Default admin password changed

Next Steps

Database Setup

Configure and optimize your database

Running in Production

Production deployment best practices

Docker Installation

Deploy with Docker using environment variables

Quickstart

Get started with Umami

Overview

Installation

Configuration

​Environment Variables

​Required Variables

​DATABASE_URL

Database Connection

​APP_SECRET

Application Secret

​Optional Configuration

​Application Settings

​PORT

​HOSTNAME

​BASE_PATH

​Tracking Configuration

​TRACKER_SCRIPT_NAME

​TRACKER_SCRIPT_URL

​COLLECT_API_ENDPOINT

​Security Settings

​FORCE_SSL

​ALLOWED_FRAME_URLS

​CORS_MAX_AGE

​Cloud Mode

​CLOUD_MODE

​CLOUD_URL

​Database Options

​DATABASE_TYPE

​SKIP_DB_CHECK

​High-Volume Options

​CLICKHOUSE_URL

​REDIS_URL

​Localization

​DEFAULT_LOCALE

​Build-Time Variables

​NEXT_TELEMETRY_DISABLED

​NODE_ENV

​NODE_OPTIONS

​Setting Environment Variables

​Local Development

​Docker Compose

​Docker Run

​Railway

​Vercel

​System Environment

​Configuration Examples

​Minimal Production Setup

​Advanced Production

​High-Volume Setup

​Troubleshooting

​Best Practices

Use Strong Secrets

Never Commit Secrets

Document Your Config

Use Different Secrets

​Next Steps

Database Setup

Running in Production

Docker Installation

Quickstart

Build docs developers (and LLMs) love

Environment Variables

Required Variables

DATABASE_URL

APP_SECRET

Optional Configuration

Application Settings

PORT

HOSTNAME

BASE_PATH

Tracking Configuration

TRACKER_SCRIPT_NAME

TRACKER_SCRIPT_URL

COLLECT_API_ENDPOINT

Security Settings

FORCE_SSL

ALLOWED_FRAME_URLS

CORS_MAX_AGE

Cloud Mode

CLOUD_MODE

CLOUD_URL

Database Options

DATABASE_TYPE

SKIP_DB_CHECK

High-Volume Options

CLICKHOUSE_URL

REDIS_URL

Localization

DEFAULT_LOCALE

Build-Time Variables

NEXT_TELEMETRY_DISABLED

NODE_ENV

NODE_OPTIONS

Setting Environment Variables

Local Development

Docker Compose

Docker Run

Railway

Vercel

System Environment

Configuration Examples

Minimal Production Setup

Advanced Production

High-Volume Setup

Troubleshooting

Best Practices

Next Steps