Environment Variables and Settings

Environment Variables

As many other applications, Dawarich uses environment variables to configure its behavior. The default docker-compose.yml file provides defaults that are good enough to deploy the app and start using it. The following environment variables are supported:

Core Settings

Environment Variable	Default Value	Description
`RAILS_ENV`	`production`	Application environment. Self-hosted instances should use `production`. `development` is for working on Dawarich itself: it reloads code when it changes and logs every SQL query. See Switching an existing instance to production.
`SECRET_KEY_BASE`	`CHANGE_ME` in `docker-compose.yml`	Signs sessions and cookies, and derives encryption keys that aren't set explicitly. Required in production. Generate a value with `openssl rand -hex 64` and keep it: changing it signs everyone out and can make encrypted data unreadable.
`SELF_HOSTED`	`true`	Set to `true` if you're self-hosting Dawarich
`APPLICATION_HOSTS`	`localhost,my.domain.com`	Application hosts, provide multiple if you want your Dawarich instance to be available by multiple domains/ip addresses. Don't put protocols here, only host names.
`APPLICATION_PROTOCOL`	`http`	Application protocol. Change to `https` if you want your Dawarich instance to be served via SSL
`DOMAIN`	`nil`	Public hostname used to build absolute URLs in outgoing emails (family invitations, digest emails, password resets). Required in production — leaving it unset will cause email delivery to fail with a URL generation error. No protocol, no trailing slash. Example: `dawarich.example.com`.
`TIME_ZONE`	`Europe/London`	Time zone. Full list of supported timezones available on Github
`DISTANCE_UNIT`	`km`	Distance unit. For miles, change to `mi`. All settings still should be provided in meters/kilometers
`MIN_MINUTES_SPENT_IN_CITY`	`60`	Minimum minutes spent in a city

Switching an existing instance to production

docker-compose.yml has set RAILS_ENV=production since Dawarich 1.3.0. Compose files from earlier versions and older copies of the Synology template default to development, and Dawarich prints a warning at startup when a self-hosted instance runs that way. To switch:

Set RAILS_ENV=production for both the dawarich_app and dawarich_sidekiq containers, in your compose file or .env.
If the app container's command is bin/dev, change it to ['bin/rails', 'server', '-p', '3000', '-b', '::'], as in docker-compose.yml.
Add every hostname and IP address you open Dawarich with, including the ones your phone apps send locations to, to APPLICATION_HOSTS. Development accepts requests to any IP address; production rejects hosts that aren't listed.
Set SECRET_KEY_BASE. If it already holds a value other than CHANGE_ME, keep it. Otherwise, if ARCHIVE_RAW_DATA=true and ARCHIVE_ENCRYPTION_KEY isn't set, first copy the old SECRET_KEY_BASE value into ARCHIVE_ENCRYPTION_KEY so existing archives stay readable. Then generate a new value with openssl rand -hex 64; everyone is signed out once.
If you haven't set the three OTP_ENCRYPTION_* variables, geocoding API keys saved in Settings → Instance (on the Settings page before 1.15.0) can't be read in production, because development encrypted them with different keys. Geocoding stays off until the key is saved again. Geocoding configured through environment variables isn't affected.
Recreate the containers with docker compose up -d.

Database Settings

Environment Variable	Default Value	Description
`DATABASE_HOST`	`dawarich_db`	Database host
`DATABASE_USERNAME`	`postgres`	Database username
`DATABASE_PASSWORD`	`password`	Database password
`DATABASE_NAME`	`dawarich_development`	Database name
`DATABASE_PORT`	`5432`	Database port
`RAILS_MAX_THREADS`	`5`	Connection pool size for the Dawarich database

Redis Settings

Environment Variable	Default Value	Description
`REDIS_URL`	`redis://dawarich_redis:6379`	Redis URL
`RAILS_CACHE_DB`	`0`	Redis cache database
`RAILS_JOB_QUEUE_DB`	`1`	Redis job queue database
`RAILS_WS_DB`	`2`	Redis WebSocket database

Background Processing

Environment Variable	Default Value	Description
`BACKGROUND_PROCESSING_CONCURRENCY`	`5`	Background processing concurrency. Should not be higher than `RAILS_MAX_THREADS`. More info on Sidekiq docs
`SIDEKIQ_USERNAME`	`nil`	Sidekiq dashboard username
`SIDEKIQ_PASSWORD`	`nil`	Sidekiq dashboard password

Reverse Geocoding

Environment Variable	Default Value	Description
`PHOTON_API_HOST`	`nil`	Photon API host. Useful if you're self-hosting your own Photon instance
`PHOTON_API_KEY`	`nil`	Photon API key. Useful if you're supporting Dawarich development on Patreon and want to use Photon API instance hosted by Freika without any limits
`PHOTON_API_USE_HTTPS`	`false`	Use HTTPS for Photon API requests. Set to true if you're using your own Photon instance behind a reverse proxy with SSL
`GEOAPIFY_API_KEY`	`nil`	Geoapify API key. Provide your own key if you want to use Geoapify reverse geocoding service
`NOMINATIM_API_HOST`	`nil`	Nominatim API host. Useful if you're self-hosting your own Nominatim instance
`NOMINATIM_API_KEY`	`nil`	Nominatim API key. Provide your own key if you want to use Nominatim reverse geocoding service
`NOMINATIM_API_USE_HTTPS`	`true`	Use HTTPS for Nominatim API requests. Set to true if you're using a Nominatim instance behind a reverse proxy with SSL
`STORE_GEODATA`	`false`	Set to `true` if you want to store geodata in the database. This will increase the size of the database and will require more disk space.

OIDC Authentication (Self-Hosted Only)

For detailed setup instructions, see the OIDC Authentication Tutorial.

Environment Variable	Default Value	Description
`OIDC_CLIENT_ID`	`nil`	OIDC client ID from your identity provider
`OIDC_CLIENT_SECRET`	`nil`	OIDC client secret from your identity provider
`OIDC_ISSUER`	`nil`	OIDC issuer URL (enables auto-discovery)
`OIDC_REDIRECT_URI`	Auto-generated	Callback URL. Defaults to `{APPLICATION_URL}/users/auth/openid_connect/callback`
`OIDC_PROVIDER_NAME`	`Openid Connect`	Custom display name for the OIDC login button
`OIDC_AUTO_REGISTER`	`true`	Automatically create accounts for new OIDC users
`OIDC_PKCE_ENABLED`	`false`	Enable PKCE (S256) for the authorization code flow. Required when your OIDC client enforces PKCE (e.g. Pocket ID, hardened Authentik/Keycloak)
`ALLOW_EMAIL_PASSWORD_REGISTRATION`	`false`	Allow traditional email/password registration alongside OIDC

Manual OIDC Configuration (Alternative to Discovery)

If your identity provider doesn't support OIDC discovery, use these instead of OIDC_ISSUER:

Environment Variable	Default Value	Description
`OIDC_HOST`	`nil`	Hostname of your identity provider
`OIDC_SCHEME`	`https`	Protocol (`https` or `http`)
`OIDC_PORT`	`443`	Port number
`OIDC_AUTHORIZATION_ENDPOINT`	`/authorize`	Authorization endpoint path
`OIDC_TOKEN_ENDPOINT`	`/token`	Token endpoint path
`OIDC_USERINFO_ENDPOINT`	`/userinfo`	User info endpoint path

Email (SMTP)

Full guide

See Configuring SMTP for provider-specific examples (Office 365, Gmail, Brevo, local Postfix), the email link protocol behavior, and a troubleshooting matrix.

Environment Variable	Default Value	Description
`SMTP_SERVER`	`nil`	Your SMTP server hostname
`SMTP_PORT`	`nil`	Your SMTP port (typically 587 for TLS)
`SMTP_DOMAIN`	`nil`	HELO/EHLO domain. For transactional relays (Brevo, Mailgun, SendGrid, Postmark, Resend), set this to your verified sender domain — typically the part after `@` in `SMTP_FROM`.
`SMTP_USERNAME`	`nil`	Your SMTP username
`SMTP_PASSWORD`	`nil`	Your SMTP password
`SMTP_FROM`	`nil`	Email address to send emails from
`SMTP_AUTHENTICATION`	`plain`	Auth mechanism. Common values: `plain`, `login` (Office 365 / Microsoft 365 requires this), and `cram_md5`. Use `none` for an unauthenticated relay. `digest_md5`, `gssapi`, `ntlm`, and `xoauth2` are also accepted but rarely useful.
`SMTP_STARTTLS`	`true`	Opportunistic TLS upgrade on port 587. Leave `true` for internet-facing relays. Set `false` only for plain SMTP on port 25 to a trusted local relay. No effect on port 465 (SMTPS / implicit TLS).
`SMTP_OPEN_TIMEOUT`	`5`	Seconds to wait for the TCP connection. Bump to `25` for slow providers.
`SMTP_READ_TIMEOUT`	`5`	Seconds to wait for an SMTP response. Bump to `25` for slow providers.

Email is required for:

Password reset
Year-end digest emails
Family invitation emails

Email links are sent as https:// regardless of APPLICATION_PROTOCOL. Plain-HTTP self-hosters need a one-line initializer override — see Configuring SMTP → Email link protocol.

Prometheus Monitoring

Environment Variable	Default Value	Description
`PROMETHEUS_EXPORTER_ENABLED`	`false`	Enable Prometheus metrics exporter
`PROMETHEUS_EXPORTER_HOST`	`0.0.0.0`	Prometheus exporter host
`PROMETHEUS_EXPORTER_PORT`	`9394`	Prometheus exporter port

warning

Important note on Prometheus exporter: even if you want to use it, make sure you have PROMETHEUS_EXPORTER_ENABLED set to false in dawarich_sidekiq container. Otherwise, you'll end up with two exporters and will have to deal with duplicate metrics. The PROMETHEUS_EXPORTER_HOST for dawarich_sidekiq should be set to dawarich_app or your name of the container.

Two-Factor Authentication (2FA)

Environment Variable	Default Value	Description
`OTP_ENCRYPTION_PRIMARY_KEY`	Derived from `SECRET_KEY_BASE` in production	Primary key for encrypting OTP secrets. Set explicitly to enable two-factor authentication.
`OTP_ENCRYPTION_DETERMINISTIC_KEY`	Derived from `SECRET_KEY_BASE` in production	Deterministic key for OTP encryption. Set explicitly to enable two-factor authentication.
`OTP_ENCRYPTION_KEY_DERIVATION_SALT`	Derived from `SECRET_KEY_BASE` in production	Salt for OTP key derivation. Set explicitly to enable two-factor authentication.

tip

These keys are used by Active Record Encryption to secure 2FA (TOTP) secrets and geocoding API keys saved in Settings → Instance. Two-factor authentication is only available when all three are set explicitly. Generate each value with openssl rand -hex 32 and keep them afterwards: changing them makes the data they encrypted unreadable. When they aren't set, development uses built-in development-only values and production derives stable keys from SECRET_KEY_BASE; see Switching an existing instance to production.

Data Archival

Environment Variable	Default Value	Description
`ARCHIVE_RAW_DATA`	`false`	Enable archival of raw import data. When enabled, original import files are preserved for potential re-processing.

User Settings

In addition to environment variables, users can configure personal settings through the UI:

Map Settings

Setting	Description
Preferred Map Layer	Default map style
Route Opacity	Transparency of route lines (0-100%)
Fog of War Meters	Resolution of fog of war tiles
Minutes Between Routes	Time gap to start a new route
Meters Between Routes	Distance gap to start a new route
Speed Colored Routes	Enable speed-based route coloring
Globe Projection	Enable 3D globe view (Map V2)
Live Map Enabled	Auto-update map with new points

Visit Settings

Setting	Description
Time Threshold Minutes	Minimum time at location for visit detection
Merge Threshold Minutes	Gap to merge nearby visits
Visits Suggestions Enabled	Enable automatic visit detection

Transportation Thresholds

Setting	Description
Walking Max Speed	Maximum speed considered walking (km/h)
Cycling Max Speed	Maximum speed considered cycling (km/h)
Driving Max Speed	Maximum speed considered driving (km/h)
Flying Min Speed	Minimum speed considered flying (km/h)

Notification Settings

Setting	Description
Digest Emails Enabled	Receive year-end digest emails

Photo Integration

Setting	Description
Immich URL	URL of your Immich instance
Immich API Key	API key for Immich
Photoprism URL	URL of your Photoprism instance
Photoprism API Key	API key for Photoprism