Environment variables

You can configure Umami with the use of environment variables. They go into the same .env file as your DATABASE_URL.

Runtime variables

Runtime variables are recognized when Umami is running. You can set your environment variables prior to starting the application.

APP_SECRET `v1.0.0`

A random string used to secure authentication tokens. Each installation should have a unique value. You can generate one with:

openssl rand -hex 32

APP_SECRET = "random string"

CLIENT_IP_HEADER `v1.24.0`

HTTP header to check for the client's IP address. This is useful when you're behind a proxy that uses non-standard headers.

CLIENT_IP_HEADER = "header name"

COLLECT_API_ENDPOINT `v1.34.0`

Allows you to send metrics to a location different than the default /api/send. This is to help you avoid some ad blockers.

COLLECT_API_ENDPOINT = "/my-custom-route"

CORS_MAX_AGE `v2.0.0`

How many seconds a CORS preflight should last. Default is 24 hours.

CORS_MAX_AGE = 86400

DATABASE_URL `v1.0.0`

DATABASE_URL = "connection string"

Connection string for your database. This is the only required variable.

DEBUG `v2.0.0`

Console logging for specific areas of the application. Values include umami:auth, umami:clickhouse, umami:kafka, umami:middleware, and umami:prisma.

DEBUG = "umami:*"

DISABLE_BOT_CHECK `v2.0.0`

By default bots are excluded from statistics. This disables checking for bots.

DISABLE_BOT_CHECK = 1

DISABLE_LOGIN `v1.26.0`

Disables the login page for the application.

DISABLE_LOGIN = 1

DISABLE_UPDATES `v1.33.0`

Disables the check for new versions of Umami.

DISABLE_UPDATES = 1

DISABLE_TELEMETRY `v2.0.0`

Umami collects completely anonymous telemetry data in order help improve the application. You can choose to disable this if you don't want to participate.

DISABLE_TELEMETRY = 1

ENABLE_TEST_CONSOLE `v2.0.0`

Enables the internal test page, {host}/console. Admin access is required. Users can manually fire pageviews and events to their websites.

ENABLE_TEST_CONSOLE = 1

FAVICON_URL `v2.18.0`

The URL of the service for displaying website icons.

FAVICON_URL = "service URL"

The default is icons.duckduckgo.com:

https://icons.duckduckgo.com/ip3/{{domain}}.ico

Some alternatives you can use:

GEO_DATABASE_URL `v2.0.0`

The URL for downloading a MaxMind-compatible GeoIP database in MMDB format. This is used for IP-based location detection when location headers from a CDN are not available.

GEO_DATABASE_URL = "https://example.com/GeoLite2-City.mmdb"

If you are running on an environment which requires you to bind to a specific hostname or port, such as Heroku, you can add these variables and start your app with npm run start-env instead of npm start.

HOSTNAME = "my.hostname.com"
PORT = 3000

IGNORE_IP `v1.0.0`

You can provide a comma-delimited list of IP addresses and CIDR ranges to exclude from data collection.

IGNORE_IP = "192.168.0.1, 10.0.0.0/24, 2001:db8::/32"

LOG_QUERY `v2.0.0`

If you are running in development mode, this will log database queries to the console for debugging.

LOG_QUERY = 1

PRIVATE_MODE `v2.11.0`

Disables all external network calls. Note, this will also disable all website icons since they come from duckduckgo.com.

PRIVATE_MODE = 1

REMOVE_TRAILING_SLASH `v1.26.0`

Removes the trailing slash from all incoming urls.

REMOVE_TRAILING_SLASH = 1

TRACKER_SCRIPT_NAME `v1.26.0`

Allows you to assign a custom name to the tracker script different from the default script.js. This is to help you avoid some ad blockers.

The .js extension is not required. The value can also be any path you choose, for example /path/to/tracker.

TRACKER_SCRIPT_NAME = "custom-script-name.js"

SKIP_LOCATION_HEADERS `v2.15.0`

Skips using known location headers for country/region/city detection and forces using the local geo database.

This is useful in environments where only the country (without region or city) header is set from the proxy or CDN (like Cloudflare’s CF-IPCountry when Network > IP Geolocationis switched to On).

SKIP_LOCATION_HEADERS = 1

Build time variables

Build time variables are only recognized during the build process. This also includes building custom Docker images. You need to set your environment variables prior to building the application.

ALLOWED_FRAME_URLS `v2.3.0`

A space-delimited list of urls allowed to host the application in an iframe.

ALLOWED_FRAME_URLS = "URLs"

BASE_PATH `v1.9.0`

If you want to host Umami under a subdirectory. You may need to update your reverse proxy settings to correctly handle the BASE_PATH prefix.

BASE_PATH = "/custom"

DATABASE_TYPE `v2.0.0`

DATABASE_TYPE = "postgresql"

The type of DB to be used. This is only required for the Docker build.

FORCE_SSL `v1.0.0`

This will send a HTTP Strict-Transport-Security response header with all requests. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security.

FORCE_SSL = 1

SKIP_DB_CHECK `v2.0.0`

Skips the check-db step in the build process. Used for Docker builds.

SKIP_DB_CHECK = 1

SKIP_DB_MIGRATION `v2.0.0`

Skips the Prisma migration step in the build process. Setting SKIP_DB_CHECK also skips this step.

SKIP_DB_MIGRATION = 1