You can configure Umami with the use of environment variables. They go into the same .env
file as your DATABASE_URL
.
Runtime variables are recognized when Umami is running. You can set your environment variables prior to starting the application.
APP_SECRET = <random string>
A unique value for your installation.
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.
CLOUD_MODE = 1
Disables users
, teams
, and websites
settings page.
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.
CORS_MAX_AGE = <number>
How many seconds a CORS preflight should last. Default is 24 hours.
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_BOT_CHECK = 1
By default bots are excluded from statistics. This disables checking for bots.
DISABLE_LOGIN = 1
Disables the login page for the application.
DISABLE_UPDATES = 1
Disables the check for new versions of Umami.
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.
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.
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 or ranges>
You can provide a comma-delimited list of IP addresses and ranges to exclude from data collection.
LOG_QUERY = 1
If you are running in development mode, this will log database queries to the console for debugging.
PRIVATE_MODE = 1
Disables all external network calls. Note, this will also disable all website icons since they come from duckduckgo.com.
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.
The .js
extension is not required. The value can also be any path you choose, for example /path/to/tracker
.
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.