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.

CLOUD_MODE = 1

Disables users, teams, and websites settings page.

CORS_MAX_AGE = <number>

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

DISABLE_BOT_CHECK = 1

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

DISABLE_LOGIN = 1

Disables the login page.

ENABLE_TEST_CONSOLE = 1

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

APP_SECRET = <random string>

A random string used to generate unique values.

CLIENT_IP_HEADER = <header name>

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

COLLECT_API_ENDPOINT = <API endpoint>

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

DATABASE_URL = <connection string>

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

DEBUG = <debug value>

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

DISABLE_UPDATES = 1

Disables the check for new versions of Umami.

DISABLE_LOGIN = 1

Disables the login page for the application.

DISABLE_TELEMETRY = 1

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.

HOSTNAME = <hostname>

PORT = <port number>

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.

IGNORE_IP = <ip addresses>

You can provide a comma-delimited list of IP address to exclude from data collection.

IGNORE_HOSTNAME = <hostname>

This will do a DNS lookup on a hostname and the resulting IP address will be ignored. This can be a comma delimited list of hostnames.

LOG_QUERY = 1

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

REMOVE_TRAILING_SLASH = 1

Removes the trailing slash from all incoming urls.

TRACKER_SCRIPT_NAME = <script name>

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.

You do not need the .js extension. It can be any path you choose, and it won't affect the correct load and execution of the script. However, be sure to use the correct path to fetch your script, to avoid 404 errors. Some examples:

TRACKER_SCRIPT_NAME=           # Unset. By default, the script is fetched from: /script.js
TRACKER_SCRIPT_NAME=custom     # Fetched from: /custom
TRACKER_SCRIPT_NAME=custom.js  # Fetched from: /custom.js

If you are not sure about the correct URL or path to access the script, you can always check the Tracking code for your website. You have more information about that in the Collect data section in the docs.

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 = <urls>

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

BASE_PATH = <path>

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.

DATABASE_TYPE = <postgresql | mysql>

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

FORCE_SSL = 1

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.

SKIP_DB_CHECK = 1

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