Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/check-env.js
• next.config.ts
• src/lib/constants.ts
• package.json
• README.md

The Umami application utilizes a multi-layered configuration system, primarily driven by environment variables, a Next.js configuration file, and a set of application-level constants. This approach allows for flexibility across different deployment environments, from local development to production and Docker-based setups.

Configuration is loaded at build time and runtime. The pnpm run build command orchestrates several configuration-dependent steps, including database checks and tracker script generation. At runtime, the Next.js server uses next.config.ts to manage request handling, headers, and environment variable exposure to the client-side application.

Environment Variables

Environment variables are the primary method for configuring the Umami application. They are typically defined in an .env file in the project root. The README.md specifies the most critical variable, DATABASE_URL, which is required for the application to connect to its PostgreSQL database.

Sources: README.md:27-31

The scripts/check-env.js script is executed during the build process to ensure that the DATABASE_URL is present, preventing the application from starting without a valid database connection.

The following diagram illustrates the flow of environment variables from the .env file to the application.

This diagram shows how environment variables are loaded and utilized by different parts of the application.
Sources: next.config.ts:2, scripts/check-env.js

Key Environment Variables

The application uses several environment variables to control its behavior. These are loaded and processed in next.config.ts.

Variable	Description	Default	Source File
DATABASE_URL	The connection URL for the PostgreSQL database.	(none)	README.md:27-31
BASE_PATH	A path prefix for the URL.	'' (empty string)	next.config.ts:6
CLOUD_MODE	Enables cloud-specific features.	'' (empty string)	next.config.ts:7
COLLECT_API_ENDPOINT	A custom endpoint for data collection, which rewrites to /api/send.	'' (empty string)	next.config.ts:9
FORCE_SSL	If set, adds the Strict-Transport-Security header to responses.	'' (empty string)	next.config.ts:11
ALLOWED_FRAME_URLS	A space-separated list of URLs allowed to embed Umami in an iframe via frame-ancestors.	'' (empty string)	next.config.ts:12
TRACKER_SCRIPT_NAME	A comma-separated list of alternative names for the tracker script.	'' (empty string)	next.config.ts:13
TRACKER_SCRIPT_URL	An external URL to use for the tracker script.	'' (empty string)	next.config.ts:14
DEFAULT_LOCALE	The default language for the application UI.	'' (empty string)	next.config.ts:10

Sources: next.config.ts:6-14

Next.js Configuration

The file next.config.ts is central to the web application's configuration. It controls HTTP headers, URL rewrites, redirects, and exposes environment variables to the client.

Sources: next.config.ts

HTTP Headers

The application defines several sets of default HTTP headers to enhance security and control caching.

• Default Headers: Applied to all paths (/:path*). Includes a Content Security Policy (CSP).
• API Headers: Applied to API routes (/api/:path*). Sets permissive CORS policies and disables caching.
• Tracker Headers: Applied to the tracker script. Allows cross-origin requests and sets a public cache policy.

The FORCE_SSL environment variable can be used to add the Strict-Transport-Security header.

// next.config.ts:31-37
if (forceSSL) {
  defaultHeaders.push({
    key: 'Strict-Transport-Security',
    value: 'max-age=63072000; includeSubDomains; preload',
  });
}

Sources: next.config.ts:16-72

URL Rewrites and Redirects

next.config.ts configures several URL rewrites and redirects to provide clean URLs and backwards compatibility.

Rewrites

Rewrites map an incoming request path to a different destination path internally.

• Custom Tracker Script Names: If TRACKER_SCRIPT_NAME is set, it creates rewrites from the custom names (e.g., /${name}) to the standard /script.js.
• Custom Collect Endpoint: If COLLECT_API_ENDPOINT is set, it rewrites that path to /api/send.
• Cloud Mode: If CLOUD_MODE is enabled, /script.js is rewritten to https://cloud.umami.is/script.js.

The following diagram shows the rewrite logic for a custom tracker script name.

Redirects

Redirects are used to permanently or temporarily move URLs. For example, /settings is redirected to /settings/preferences.

// next.config.ts:107-111
const redirects = [
  {
    source: '/settings',
    destination: '/settings/preferences',
    permanent: false,
  },
//...

Sources: next.config.ts:106-127

Build and Startup Process

The package.json file defines scripts that control the application's lifecycle. The build script is a composite command that relies on several configuration-aware sub-scripts.

// package.json:11-12
"scripts": {
  "build": "npm-run-all check-env build-db check-db build-tracker build-geo build-app",

The build process is visualized below.

This flow demonstrates the importance of the DATABASE_URL environment variable, which is validated at the very beginning of the build process.

Sources: package.json:11-12, scripts/check-env.js

Application Constants

The file src/lib/constants.ts centralizes a wide range of static configuration values used throughout the application. These constants define default behaviors, token names, API URLs, and data model enumerations.

Configuration Constants

These constants define keys for storing user preferences in local storage and set default values.

Constant	Value	Description
AUTH_TOKEN	umami.auth	The key for storing the authentication token.
LOCALE_CONFIG	umami.locale	The key for storing the user's selected locale.
THEME_CONFIG	umami.theme	The key for storing the user's selected theme.
DEFAULT_LOCALE	en-US	The default locale if none is configured.
DEFAULT_THEME	light	The default theme if none is configured.
DEFAULT_DATE_RANGE_VALUE	24hour	The default date range for analytics views.

Sources: src/lib/constants.ts:2-7, 18-21

Data Model and Permissions

The file also defines critical enumerations for the data model, such as roles and permissions, which govern access control within the application.

// src/lib/constants.ts:114-123
export const ROLES = {
  admin: 'admin',
  user: 'user',
  viewOnly: 'view-only',
  teamOwner: 'team-owner',
  teamManager: 'team-manager',
  teamMember: 'team-member',
  teamViewOnly: 'team-view-only',
} as const;

A mapping between roles and their granted permissions is also defined, forming the core of the application's role-based access control (RBAC) system.

Sources: src/lib/constants.ts:114-152