Environment Variables Reference
This page is the canonical environment variable reference for GeoPulse. Every listed variable includes default value, comments, restrictions, and restart guidance.
- Frontend runtime source:
frontend/docker-entrypoint.sh - Backend runtime source:
backend/src/main/resources/application.properties - Deployment source:
.env.example,docker-compose*.yml, and Helm templates
Frontend Runtime Vars
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_BACKEND_URL | http://geopulse-backend:8080 | Backend upstream URL injected into Nginx reverse-proxy config. | Reachable HTTP URL from frontend container network. | Frontend container restart |
CLIENT_MAX_BODY_SIZE | 200M | Nginx `client_max_body_size` for uploads. | Nginx size format (for example `200M`, `1G`). | Frontend container restart |
OSM_RESOLVER | Auto-detected (\127.0.0.11 8.8.8.8` in Docker)` | DNS resolvers used by Nginx for OpenStreetMap tile hosts. | Space-separated resolver IPs reachable from container. | Frontend container restart |
Backend Runtime Vars
Backend runtime currently includes 337 distinct env vars.
Notes:
GEOPULSE_AUTH_SIGN_UP_ENABLEDis deprecated but still supported for backward compatibility.- Runtime env changes require backend restart to take effect.
Core and Database (11)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_CORS_ENABLED | true | Enables/disables backend CORS handling. Property: quarkus.http.cors.enabled. New .env.example sets this to false for same-origin nginx deployments. | true or false. | Backend restart |
GEOPULSE_CORS_ORIGINS | (falls back to GEOPULSE_UI_URL) | Comma-separated CORS origins when CORS is enabled. Property: quarkus.http.cors.origins. | One URL or comma-separated URLs. | Backend restart |
GEOPULSE_DATABASE_TRANSACTION_TIMEOUT_MINUTES | 60 | Default database transaction timeout. Import processing has its own timeout. Property: `quarkus.transaction-manager.default-transaction-timeout`. | Non-negative numeric value. | Backend restart |
GEOPULSE_AVATAR_MAX_SIZE_BYTES | 1048576 | Maximum allowed size for uploaded custom avatars (in bytes). Property: geopulse.avatar.max-size-bytes. | Positive integer value (bytes). | Backend restart |
GEOPULSE_POSTGRES_PASSWORD | (required/no default) | PostgreSQL configuration Property: `quarkus.datasource.password`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_POSTGRES_URL | (required/no default) | PostgreSQL configuration Property: `quarkus.datasource.jdbc.url`. | Valid PostgreSQL JDBC URL (`jdbc:postgresql://...`). | Backend restart |
GEOPULSE_POSTGRES_USERNAME | (required/no default) | PostgreSQL configuration Property: `quarkus.datasource.username`. | Required; no default value is provided. | Backend restart |
GEOPULSE_PUBLIC_BASE_URL | (empty) | Public base URL used for callback/link generation. Property: geopulse.public-base-url. | Valid URL. | Backend restart |
GEOPULSE_UI_URL | http://localhost:5555 | Legacy fallback variable for CORS origins and OIDC callback fallback. Deprecated: use GEOPULSE_CORS_ORIGINS and GEOPULSE_PUBLIC_BASE_URL. | One URL or comma-separated URLs. | Backend restart |
GEOPULSE_PROXY_ADDRESS_FORWARDING | false | Trust X-Forwarded-* / Forwarded headers from a reverse proxy when the backend resolves the request scheme, host, and client address. Property: quarkus.http.proxy.proxy-address-forwarding. | true or false. Enable only when the backend is reachable exclusively through your proxy. | Backend restart |
GEOPULSE_TRUSTED_PROXIES | (empty) | Restrict forwarded-header trust to these proxy addresses when GEOPULSE_PROXY_ADDRESS_FORWARDING=true. Empty trusts any sender. Property: quarkus.http.proxy.trusted-proxies. | Comma-separated IP addresses, CIDR ranges, or hostnames. | Backend restart |
Logging (4)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_LOG_LEVEL | (unset) | Fallback application log level when no Admin override exists. Property: geopulse.log.level. | ERROR, WARN, INFO, or DEBUG; case-insensitive. TRACE is not available in production. | Backend restart |
GEOPULSE_LOG_JSON_ENABLED | true in production | Emit backend console records as JSON with flattened MDC fields (requestId, errorId). | true or false. | Backend restart |
GEOPULSE_HTTP_ACCESS_LOG_ENABLED | true in production | Emit one sanitized backend request record, excluding health, metrics, invitation, and public share-token paths. | true or false. | Backend restart |
GEOPULSE_MQTT_VERBOSE_LOGGING | false | Enables verbose Mosquitto and authentication-plugin diagnostics. Debug output may expose credential material; enable only temporarily. | true or false. | Mosquitto restart |
Version Update Check (5)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_VERSION_CHECK_GITHUB_API_URL | https://api.github.com/repos/tess1o/geopulse/releases/latest | GitHub Releases API endpoint used to resolve the latest public GeoPulse release. Property: geopulse.version-check.github-api-url. | Valid URL returning GitHub release JSON. | Backend restart |
GEOPULSE_VERSION_CHECK_RELEASE_URL | https://github.com/tess1o/geopulse/releases | Fallback/public release page URL shown to users when an update is available. Property: geopulse.version-check.release-url. | Valid URL. | Backend restart |
GEOPULSE_VERSION_CHECK_CACHE_TTL_MINUTES | 60 | Cache TTL for latest-release metadata to reduce GitHub API calls. Property: geopulse.version-check.cache-ttl-minutes. | Positive integer minutes. | Backend restart |
GEOPULSE_VERSION_CHECK_CONNECT_TIMEOUT_SECONDS | 5 | HTTP connect timeout for the GitHub latest-release lookup. Property: geopulse.version-check.connect-timeout-seconds. | Positive integer seconds. | Backend restart |
GEOPULSE_VERSION_CHECK_READ_TIMEOUT_SECONDS | 8 | HTTP read timeout for the GitHub latest-release lookup. Property: geopulse.version-check.read-timeout-seconds. | Positive integer seconds. | Backend restart |
Authentication and Access (24)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_ADMIN_EMAIL | (empty) | Admin configuration Property: `geopulse.admin.email`. | Valid email address. | Backend restart |
GEOPULSE_FIRST_USER_ADMIN | true | Promotes the first registered user to ADMIN when GEOPULSE_ADMIN_EMAIL is empty. Property: `geopulse.admin.first-user-admin.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_ADMIN_LOGIN_BYPASS_ENABLED | true | Property: `geopulse.auth.admin-login-bypass.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_GUEST_ROOT_REDIRECT_TO_LOGIN_ENABLED | false | Redirect signed-out users from / to /login instead of rendering Home. Property: `geopulse.auth.guest-root-redirect-to-login.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_MOBILE_CODE_EXPIRY_SECONDS | 5 | Lifetime of one-time mobile session exchange code in seconds. Property: `geopulse.auth.mobile.code-expiry-seconds`. | Positive integer seconds. | Backend restart |
GEOPULSE_AUTH_MOBILE_DEEPLINK_URL | app://auth/code/exchange | Deep link URL used by web flow to open the mobile app for session exchange. Property: `geopulse.auth.mobile.deeplink.url`. | Valid mobile deep link URI. | Backend restart |
GEOPULSE_AUTH_MOBILE_DEEPLINK_CLEANUP_CRON | 0 0 3 1 * ? | Cron expression for cleanup of expired mobile deep-link auth codes (default: day 1 of month at 03:00). Property: `geopulse.auth.mobile.deeplink.cleanup.cron`. | Valid Quarkus cron expression. | Backend restart |
GEOPULSE_AUTH_MOBILE_DEEPLINK_CLEANUP_ENABLED | true | Enables/disables scheduled cleanup of expired mobile deep-link auth codes. Property: `geopulse.auth.mobile.deeplink.cleanup.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_LOGIN_ENABLED | true | Property: `geopulse.auth.login.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_OIDC_AUTO_LAUNCH_ENABLED | false | With password login disabled and exactly one OIDC provider, /login goes straight to that provider (after a sign-out only once the user presses Sign in, never after a failed sign-in; /login?autoLaunch=0 always shows the page). Property: `geopulse.auth.oidc.auto-launch.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_OIDC_LOGIN_ENABLED | true | Property: `geopulse.auth.oidc.login.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_OIDC_REGISTRATION_ENABLED | true | Property: `geopulse.auth.oidc.registration.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_PASSWORD_LOGIN_ENABLED | true | Property: `geopulse.auth.password-login.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_PASSWORD_REGISTRATION_ENABLED | true | Property: `geopulse.auth.password-registration.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_REGISTRATION_ENABLED | true | Property: `geopulse.auth.registration.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_SECURE_COOKIES | false | Property: `geopulse.auth.secure-cookies`. | `true` or `false`. | Backend restart |
GEOPULSE_AUTH_SIGN_UP_ENABLED | true | Deprecated property, replaced by geopulse.auth.password-registration.enabled Property: `geoupuse.auth.sign-up-enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_COOKIE_DOMAIN | (empty) | Property: `geopulse.auth.cookie-domain`. | Optional; empty value uses fallback behavior. | Backend restart |
GEOPULSE_INVITATION_BASE_URL | (empty) | User invitation configuration Base URL for generating invitation links (e.g., https://geopulse.example.com) If empty, frontend will use window.location.origin Property: `geopulse.invitation.base-url`. | Valid URL. | Backend restart |
GEOPULSE_AUTH_SESSION_IDLE_TIMEOUT | 7d | A sign-in session ends after this long without use. Property: `geopulse.auth.session.idle-timeout`. | Duration, e.g. `12h`, `7d`. | Backend restart |
GEOPULSE_AUTH_SESSION_ABSOLUTE_TIMEOUT | 90d | A sign-in session ends at the latest this long after sign-in, even when in use. Property: `geopulse.auth.session.absolute-timeout`. | Duration, e.g. `30d`. | Backend restart |
GEOPULSE_AUTH_ACCESS_TOKEN_LIFESPAN | 30m | Access token lifetime for API sessions and the mobile app; renewed with the refresh token. Property: `geopulse.auth.session.access-token-lifespan`. | Duration, e.g. `15m`. | Backend restart |
GEOPULSE_AUTH_SESSION_CLEANUP_RETENTION | 7d | How long ended sessions are kept before they are deleted. Property: `geopulse.auth.session.cleanup.retention`. | Duration. | Backend restart |
GEOPULSE_USER_DEFAULT_DISTANCE_UNIT | KILOMETERS | Default distance unit for newly created users. Property: `geopulse.user.default-distance-unit`. Existing users keep their profile preference. | KILOMETERS or MILES. | Backend restart |
GEOPULSE_USER_DEFAULT_TEMPERATURE_UNIT | CELSIUS | Default temperature unit for newly created users. Property: `geopulse.user.default-temperature-unit`. Existing users keep their profile preference. | CELSIUS or FAHRENHEIT. | Backend restart |
OIDC Core (6)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_OIDC_AUTO_LINK_ACCOUNTS | false | Account Linking Security When true, automatically links OIDC accounts to existing users with matching emails WARNING: Only enable this if you fully trust your OIDC providers to... Property: `geopulse.oidc.auto-link-accounts`. | `true` or `false`. | Backend restart |
GEOPULSE_OIDC_CALLBACK_BASE_URL | (empty) | OIDC callback base URL. Fallback order: GEOPULSE_PUBLIC_BASE_URL, then legacy GEOPULSE_UI_URL. Property: geopulse.oidc.callback-base-url. | Valid URL. | Backend restart |
GEOPULSE_OIDC_CLEANUP_ENABLED | true | OIDC Cleanup Configuration Property: `geopulse.oidc.cleanup.session-states.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_OIDC_ENABLED | false | OIDC Configuration Property: `geopulse.oidc.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_OIDC_RP_LOGOUT_ENABLED | true | When signing out of GeoPulse, also sign out of the OIDC provider if it publishes an `end_session_endpoint` (RP-initiated logout). Best effort. Property: `geopulse.oidc.rp-logout.enabled`. Also in Admin → Settings → Authentication. | `true` or `false`. | Immediate (Admin UI) / Backend restart |
GEOPULSE_OIDC_JWKS_CACHE_TTL_HOURS | 24 | JWKS (signing keys) caching Lower TTL recommended to handle provider key rotation Property: `geopulse.oidc.jwks-cache.ttl-hours`. | Non-negative numeric value. | Backend restart |
AI, Immich, and Memos (10)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_AI_CHAT_MEMORY_MAX_MESSAGES | 10 | AI Feature Configuration Property: `geopulse.ai.chat-memory.max-messages`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_AI_ENCRYPTION_KEY_LOCATION | file:/app/keys/ai-encryption-key.txt | AI Feature Configuration Property: `geopulse.ai.encryption.key.location`. | Readable path/URI in container filesystem. | Backend restart |
GEOPULSE_AI_LOGGING_ENABLED | false | AI Feature Configuration Property: `geopulse.ai.logging.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_AI_TOOL_RESULT_MAX_LENGTH | 12000 | AI Feature Configuration Property: `geopulse.ai.tool-result.max-length`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMMICH_GEONAMES_NORMALIZATION_MAX_DISTANCE_METERS | 50000 | Immich search cache Property: `immich.photos.geonames-normalization.max-distance-meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMMICH_PHOTO_SEARCH_CACHE_MAX_ENTRIES | 200 | Immich search cache Property: `immich.photos.search-cache-max-entries`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMMICH_PHOTO_SEARCH_CACHE_TTL_SECONDS | 300 | Immich search cache Property: `immich.photos.search-cache-ttl-seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_IMMICH_PHOTO_SEARCH_TIMEOUT_SECONDS | 15 | Immich search timeout Property: `immich.photos.search-timeout-seconds`. | Positive numeric value. | Backend restart |
GEOPULSE_MEMOS_NOTES_SEARCH_CACHE_MAX_ENTRIES | 200 | Memos notes search cache maximum entries. Property: `geopulse.memos.notes.search-cache-max-entries`. | Positive integer value. | Backend restart |
GEOPULSE_MEMOS_NOTES_SEARCH_CACHE_TTL_SECONDS | 300 | Memos notes search cache TTL in seconds. Property: `geopulse.memos.notes.search-cache-ttl-seconds`. | Positive integer seconds. | Backend restart |
Geocoding and GeoNames (51)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_GEOCODING_DELAY_MS | 1000 | Delay between geocoding requests (milliseconds) Property: `geocoding.provider.delay.ms`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_CACHE_MAX_BBOX_AREA_KM2 | 5000 | Maximum provider bbox area accepted for cache containment matching. Oversized bboxes are dropped and matching falls back to coordinate tolerance. Property: `geocoding.cache.max-bbox-area-km2`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_RETRY_MAX_RETRIES | 5 | Maximum retry attempts for geocoding provider calls Property: `quarkus.fault-tolerance.global.retry.max-retries`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_RETRY_DELAY_MS | 1250 | Delay between geocoding provider retry attempts (milliseconds) Property: `quarkus.fault-tolerance.global.retry.delay`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_RETRY_JITTER_MS | 250 | Retry delay jitter for geocoding provider calls (milliseconds) Property: `quarkus.fault-tolerance.global.retry.jitter`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_CB_FAILURE_RATIO | 0.7 | Circuit breaker failure ratio threshold for geocoding provider calls Property: `quarkus.fault-tolerance.global.circuit-breaker.failure-ratio`. | Decimal between 0 and 1. | Backend restart |
GEOPULSE_GEOCODING_CB_REQUEST_VOLUME | 10 | Circuit breaker rolling window size for geocoding provider calls Property: `quarkus.fault-tolerance.global.circuit-breaker.request-volume-threshold`. | Positive numeric value. | Backend restart |
GEOPULSE_GEOCODING_CB_DELAY_SECONDS | 20 | Circuit breaker open-state delay before half-open probe (seconds) Property: `quarkus.fault-tolerance.global.circuit-breaker.delay`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_CB_SUCCESS_THRESHOLD | 2 | Successful half-open calls required to close geocoding circuit breaker Property: `quarkus.fault-tolerance.global.circuit-breaker.success-threshold`. | Positive numeric value. | Backend restart |
GEOPULSE_GEOCODING_RECONCILE_ITEM_MAX_ATTEMPTS | 4 | Maximum attempts per record during geocoding reconciliation jobs Property: `geocoding.reconcile.item.max-attempts`. | Positive numeric value. | Backend restart |
GEOPULSE_GEOCODING_RECONCILE_CIRCUIT_OPEN_WAIT_MS | 20000 | Wait before retrying reconciliation when circuit breaker is open (milliseconds) Property: `geocoding.reconcile.circuit-open-wait.ms`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_RECONCILE_INTER_ITEM_DELAY_MS | 1000 | Delay between reconciliation job items (milliseconds) Property: `geocoding.reconcile.inter-item-delay.ms`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_FALLBACK_PROVIDER | photon | Fallback geocoding provider (optional) Property: `geocoding.provider.fallback`. | Empty or one of `nominatim`, `photon`, `googlemaps`, `mapbox`, `geoapify`, `chibigeo`. | Backend restart |
GEOPULSE_GEOCODING_GEOAPIFY_API_KEY | (empty) | Geoapify API key Property: `geocoding.geoapify.api-key`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_GEOCODING_GEOAPIFY_DELAY_MS | 0 | Delay between Geoapify requests. Property: `geocoding.provider.geoapify.delay.ms`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_GEOAPIFY_ENABLED | false | Property: `geocoding.provider.geoapify.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEOCODING_GEOAPIFY_LANGUAGE | (empty) | Geoapify language preference Property: `geocoding.geoapify.language`. | Language code or empty. | Backend restart |
GEOPULSE_GEOCODING_CHIBIGEO_API_KEY | (empty) | ChibiGeo API key sent as `X-Api-Key` Property: `geocoding.chibigeo.api-key`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_GEOCODING_CHIBIGEO_DELAY_MS | 0 | Delay between ChibiGeo requests. Property: `geocoding.provider.chibigeo.delay.ms`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEOCODING_CHIBIGEO_ENABLED | false | Property: `geocoding.provider.chibigeo.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEOCODING_CHIBIGEO_URL | https://app.chibigeo.com/v1/photon | ChibiGeo Photon-compatible endpoint Property: `quarkus.rest-client.chibigeo-api.url`. | Valid URL. | Backend restart |
GEOPULSE_GEOCODING_CHIBIGEO_LANGUAGE | (empty) | ChibiGeo Photon-compatible language preference Property: `geocoding.chibigeo.language`. | One Photon-supported code or empty. | Backend restart |
GEOPULSE_GEOCODING_GOOGLE_MAPS_API_KEY | (empty) | API Keys (can also be set via encrypted storage in admin panel) Property: `geocoding.googlemaps.api-key`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_GEOCODING_GOOGLE_MAPS_ENABLED | false | Property: `geocoding.provider.googlemaps.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEOCODING_GOOGLE_MAPS_LANGUAGE | (empty) | Google Maps reverse geocoding language preference sent as the language query param. Property: `geocoding.googlemaps.language`. | Google supported language code (for example `en`, `uk`, `pt-BR`, `zh-CN`) or empty. | Backend restart |
GEOPULSE_GEOCODING_MAPBOX_ACCESS_TOKEN | (empty) | Property: `geocoding.mapbox.access-token`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_GEOCODING_MAPBOX_ENABLED | false | Property: `geocoding.provider.mapbox.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEOCODING_NOMINATIM_ENABLED | true | Provider availability flags Property: `geocoding.provider.nominatim.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEOCODING_NOMINATIM_PUBLIC_HOST_FORWARD_SEARCH_ENABLED | false | Allow Nominatim forward search/autocomplete on public `nominatim.openstreetmap.org` (self-hosted Nominatim is allowed even when this is `false`). Property: `geocoding.nominatim.public-host-forward-search-enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEOCODING_NOMINATIM_LANGUAGE | (empty) | Provider availability flags Nominatim geocoding language preference (BCP 47 format: en-US, de, uk, ja, etc.) If not set, no Accept-Language header will be sent (existing behavior) Property: `geocoding.nominatim.language`. | BCP 47 language tag (for example `en-US`) or empty. | Backend restart |
GEOPULSE_GEOCODING_NOMINATIM_URL | https://nominatim.openstreetmap.org | Provider availability flags Property: `quarkus.rest-client.nominatim-api.url`. | Valid URL. | Backend restart |
GEOPULSE_GEOCODING_PHOTON_ENABLED | true | Property: `geocoding.provider.photon.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEOCODING_PHOTON_LANGUAGE | (empty) | Photon geocoding language preference. Allowed values: `de`, `pl`, `el`, `en`, `es`, `fa`, `fr`, `it`, `ja`, `ko`. If not set, no Accept-Language header/lang query parameter will be sent (existing behavior). Property: `geocoding.photon.language`. | One allowed code or empty. | Backend restart |
GEOPULSE_GEOCODING_PHOTON_URL | https://photon.komoot.io | Property: `quarkus.rest-client.photon-api.url`. | Valid URL. | Backend restart |
GEOPULSE_GEOCODING_PRIMARY_PROVIDER | nominatim | Primary geocoding provider (nominatim, photon, googlemaps, mapbox, geoapify, chibigeo) Property: `geocoding.provider.primary`. | One of `nominatim`, `photon`, `googlemaps`, `mapbox`, `geoapify`, `chibigeo`. | Backend restart |
GEOPULSE_GEONAMES_COUNTRY_IMPORT_BATCH_SIZE | 200 | GeoNames country dataset import (ISO2 -> country metadata) Property: `geopulse.geonames.country-import.batch-size`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_GEONAMES_COUNTRY_IMPORT_CONNECT_TIMEOUT_SECONDS | 20 | GeoNames country dataset import (ISO2 -> country metadata) Property: `geopulse.geonames.country-import.connect-timeout-seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEONAMES_COUNTRY_IMPORT_ENABLED | true | GeoNames country dataset import (ISO2 -> country metadata) Property: `geopulse.geonames.country-import.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEONAMES_COUNTRY_IMPORT_FORCE_REFRESH | false | GeoNames country dataset import (ISO2 -> country metadata) Property: `geopulse.geonames.country-import.force-refresh`. | `true` or `false`. | Backend restart |
GEOPULSE_GEONAMES_COUNTRY_IMPORT_MIN_ROW_THRESHOLD | 200 | GeoNames country dataset import (ISO2 -> country metadata) Property: `geopulse.geonames.country-import.min-row-threshold`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_GEONAMES_COUNTRY_IMPORT_READ_TIMEOUT_SECONDS | 120 | GeoNames country dataset import (ISO2 -> country metadata) Property: `geopulse.geonames.country-import.read-timeout-seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEONAMES_COUNTRY_IMPORT_URL | https://download.geonames.org/export/dump/countryInfo.txt | GeoNames country dataset import (ISO2 -> country metadata) Property: `geopulse.geonames.country-import.url`. | Valid URL. | Backend restart |
GEOPULSE_GEONAMES_IMPORT_BATCH_SIZE | 1000 | GeoNames cities dataset import (used for city normalization) Property: `geopulse.geonames.import.batch-size`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_GEONAMES_IMPORT_CONNECT_TIMEOUT_SECONDS | 20 | GeoNames cities dataset import (used for city normalization) Property: `geopulse.geonames.import.connect-timeout-seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEONAMES_IMPORT_ENABLED | true | GeoNames cities dataset import (used for city normalization) Property: `geopulse.geonames.import.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GEONAMES_IMPORT_FORCE_REFRESH | false | GeoNames cities dataset import (used for city normalization) Property: `geopulse.geonames.import.force-refresh`. | `true` or `false`. | Backend restart |
GEOPULSE_GEONAMES_IMPORT_MIN_ROW_THRESHOLD | 100000 | GeoNames cities dataset import (used for city normalization) Property: `geopulse.geonames.import.min-row-threshold`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_GEONAMES_IMPORT_READ_TIMEOUT_SECONDS | 300 | GeoNames cities dataset import (used for city normalization) Property: `geopulse.geonames.import.read-timeout-seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GEONAMES_IMPORT_URL | https://download.geonames.org/export/dump/cities500.zip | GeoNames cities dataset import (used for city normalization) Property: `geopulse.geonames.import.url`. | Valid URL. | Backend restart |
GEOPULSE_TIMEZONE_LOCATION_ENABLED | true | Location-local times: lets users show timeline and GPS data times in the timezone of the nearest GeoNames city. Set to `false` to switch the feature off for everyone; users then see profile-timezone times. Property: `geopulse.timezone.location.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMEZONE_LOCATION_MAX_DISTANCE_KM | 200 | Location-local times: cities farther than this are ignored (open sea, polar regions) and the profile timezone is used. Property: `geopulse.timezone.location.max-distance-km`. | Positive numeric value. | Backend restart |
Import (18)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_IMPORT_BULK_INSERT_BATCH_SIZE | 500 | Import batch size configuration Property: `geopulse.import.bulk-insert-batch-size`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMPORT_CHUNK_SIZE_MB | 50 | Chunked upload configuration (for bypassing Cloudflare's 100MB upload limit) Files >80MB are split into chunks on the frontend and reassembled on the backend Property: `geopulse.import.chunk-size-mb`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMPORT_CHUNKS_DIR | /tmp/geopulse/chunks | Chunked upload configuration (for bypassing Cloudflare's 100MB upload limit) Files >80MB are split into chunks on the frontend and reassembled on the backend Property: `geopulse.import.chunks-directory`. | Readable path/URI in container filesystem. | Backend restart |
GEOPULSE_IMPORT_DROP_FOLDER_ENABLED | false | Drop folder import configuration (server-side file pickup) Property: `geopulse.import.drop-folder.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_IMPORT_DROP_FOLDER_GEOPULSE_MAX_SIZE_MB | 200 | Drop folder import configuration (server-side file pickup) Property: `geopulse.import.drop-folder.geopulse-max-size-mb`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMPORT_DROP_FOLDER_PATH | /data/geopulse-import | Drop folder import configuration (server-side file pickup) Property: `geopulse.import.drop-folder.path`. | Readable path/URI in container filesystem. | Backend restart |
GEOPULSE_IMPORT_DROP_FOLDER_POLL_INTERVAL_SECONDS | 10 | Drop folder import configuration (server-side file pickup) Property: `geopulse.import.drop-folder.poll-interval-seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_IMPORT_DROP_FOLDER_STABLE_AGE_SECONDS | 10 | Drop folder import configuration (server-side file pickup) Property: `geopulse.import.drop-folder.stable-age-seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_IMPORT_GEOJSON_STREAMING_BATCH_SIZE | 500 | GeoJSON streaming parser configuration Batch size for streaming GeoJSON imports - aligns with bulk insert batch size for optimal performance During streaming, batches are flushe... Property: `geopulse.import.geojson.streaming-batch-size`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMPORT_GOOGLETIMELINE_STREAMING_BATCH_SIZE | 500 | Google Timeline streaming parser configuration Batch size for streaming Google Timeline imports - aligns with bulk insert batch size for optimal performance During streaming, ba... Property: `geopulse.import.googletimeline.streaming-batch-size`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMPORT_LARGE_FILE_THRESHOLD_MB | 100 | Import temp file configuration (for large file handling) Files larger than this threshold are saved to temp directory instead of loading into memory This prevents OOM errors wit... Property: `geopulse.import.large-file-threshold-mb`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMPORT_MAX_FILE_SIZE_GB | 10 | Chunked upload configuration (for bypassing Cloudflare's 100MB upload limit) Files >80MB are split into chunks on the frontend and reassembled on the backend Property: `geopulse.import.max-file-size-gb`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMPORT_MERGE_BATCH_SIZE | 250 | Import batch size configuration Property: `geopulse.import.merge-batch-size`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_IMPORT_TEMP_DIR | /tmp/geopulse/imports | Import temp file configuration (for large file handling) Files larger than this threshold are saved to temp directory instead of loading into memory This prevents OOM errors wit... Property: `geopulse.import.temp-directory`. | Readable path/URI in container filesystem. | Backend restart |
GEOPULSE_IMPORT_TEMP_FILE_RETENTION_HOURS | 24 | Import temp file configuration (for large file handling) Files larger than this threshold are saved to temp directory instead of loading into memory This prevents OOM errors wit... Property: `geopulse.import.temp-file-retention-hours`. | Non-negative numeric value. | Backend restart |
GEOPULSE_IMPORT_TRANSACTION_TIMEOUT_MINUTES | 1440 | Transaction timeout for import processing only. Reverse-geocoding data is committed separately and survives import rollback. Property: `geopulse.import.transaction-timeout-minutes`. | Positive integer minutes. | Backend restart |
GEOPULSE_IMPORT_UPLOAD_CLEANUP_MINUTES | 15 | Chunked upload configuration (for bypassing Cloudflare's 100MB upload limit) Files >80MB are split into chunks on the frontend and reassembled on the backend Property: `geopulse.import.upload-cleanup-minutes`. | Non-negative numeric value. | Backend restart |
GEOPULSE_IMPORT_UPLOAD_TIMEOUT_HOURS | 2 | Chunked upload configuration (for bypassing Cloudflare's 100MB upload limit) Files >80MB are split into chunks on the frontend and reassembled on the backend Property: `geopulse.import.upload-timeout-hours`. | Non-negative numeric value. | Backend restart |
Export (8)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_EXPORT_BATCH_SIZE | 1000 | Batch sizes for streaming exports Property: `geopulse.export.batch-size`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_EXPORT_CONCURRENT_JOBS_LIMIT | 3 | Export configuration Job management settings Property: `geopulse.export.concurrent-jobs-limit`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_EXPORT_JOB_EXPIRY_HOURS | 24 | Export configuration Job management settings Property: `geopulse.export.job-expiry-hours`. | Non-negative numeric value. | Backend restart |
GEOPULSE_EXPORT_MAX_JOBS_PER_USER | 5 | Export configuration Job management settings Property: `geopulse.export.max-jobs-per-user`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_EXPORT_SCHEDULER_INTERVAL | 2s | Export configuration Job management settings Scheduler interval for processing export jobs (uses Quarkus time expression format) Note: This setting requires application restart... Property: `geopulse.export.scheduler-interval`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_EXPORT_TEMP_DIR | /tmp/geopulse/exports | Export temp file configuration (for large file handling) Export files are written to temp directory and streamed to clients to prevent OOM Property: `geopulse.export.temp-directory`. | Readable path/URI in container filesystem. | Backend restart |
GEOPULSE_EXPORT_TEMP_FILE_RETENTION_HOURS | 24 | Export temp file configuration (for large file handling) Export files are written to temp directory and streamed to clients to prevent OOM Property: `geopulse.export.temp-file-retention-hours`. | Non-negative numeric value. | Backend restart |
GEOPULSE_EXPORT_TRIP_POINT_LIMIT | 10000 | Batch sizes for streaming exports Property: `geopulse.export.trip-point-limit`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
Backup and Restore (11)
Full backup settings can be managed in Administration > Settings > Backup. For these six admin-backed settings, database values take precedence; the environment variable is used only when no saved system_settings value exists.
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_BACKUP_PASSWORD | (empty) | Password used for new encrypted .gpb backups. Saved admin values are encrypted in GeoPulse; environment values are ordinary deployment secrets. Property: `geopulse.backup.password`. | Sensitive secret; 12-1024 characters for new backups. Keep a recovery copy outside GeoPulse. | Backend restart |
GEOPULSE_BACKUP_SCHEDULED_ENABLED | false | Enables scheduled full backups. Property: `geopulse.backup.scheduled.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_BACKUP_SCHEDULED_CRON | 0 0 3 * * ? | Cron expression for scheduled full backups. Property: `geopulse.backup.scheduled.cron`. | Valid Quarkus cron expression. | Backend restart |
GEOPULSE_BACKUP_LOCAL_PATH | /data/geopulse-backups | Folder where encrypted full backup files are published and listed. Property: `geopulse.backup.local.path`. | Writable directory for the backend user. | Backend restart |
GEOPULSE_BACKUP_RETENTION_COUNT | 7 | Number of local encrypted full backups retained after a successful backup. Property: `geopulse.backup.retention.count`. | Non-negative integer. | Backend restart |
GEOPULSE_BACKUP_OPERATION_TIMEOUT_MINUTES | 120 | Maximum duration for full backup and restore operations. Property: `geopulse.backup.operation.timeout-minutes`. | Positive integer minutes. | Backend restart |
GEOPULSE_BACKUP_WORK_PATH | /data/geopulse-backups/.work | Persistent private work directory for restore journals, encrypted uploads, and temporary extracted dumps. Property: `geopulse.backup.work-path`. | Writable directory on durable storage; must survive backend/container/pod replacement. | Backend restart |
GEOPULSE_BACKUP_BINARY_DIRECTORY | (empty) | Directory containing pg_dump and pg_restore for the server's major version. When empty, GeoPulse uses the installed clients matching the server (/usr/libexec/postgresql<major>, /usr/pgsql-<major>/bin or /usr/lib/postgresql/<major>/bin), otherwise PATH. GeoPulse images ship PostgreSQL 17 and 18 clients. Property: `geopulse.backup.binary-directory`. | Directory with executable PostgreSQL client tools matching the server major version. | Backend restart |
GEOPULSE_BACKUP_MAINTENANCE_DATABASE | postgres | Database used for restore coordination and activation. Property: `geopulse.backup.maintenance-database`. | Existing database reachable by the restore role. | Backend restart |
GEOPULSE_BACKUP_RESTORE_USERNAME | (empty) | Optional dedicated restore role username; empty falls back to the application datasource username. Property: `geopulse.backup.restore.username`. | Role must be able to create/rename databases, manage connections, create required extensions, and assume the application role. | Backend restart |
GEOPULSE_BACKUP_RESTORE_PASSWORD | (empty) | Password for the dedicated restore role; empty falls back to the application datasource password. Property: `geopulse.backup.restore.password`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
Coverage (1)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_COVERAGE_PROCESSING_BATCH_SIZE | 50000 | Number of GPS points processed per coverage calculation batch. Larger values are faster but may use more PostgreSQL temporary disk space. Property: `geopulse.coverage.processing.batch-size`. | Positive integer value. | Backend restart |
Timeline and Trip Intelligence (94)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_BOAT_WATER_EVIDENCE_MAINTENANCE_INTERVAL | 15m | Interval for the Boat water-evidence maintenance job, which repairs missed or stale GPS water-evidence rows for Boat-enabled users. Property: `geopulse.boat.water-evidence.maintenance.interval`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_BOAT_WATER_EVIDENCE_MAINTENANCE_MAX_USERS_PER_RUN | 25 | Maximum number of Boat-enabled users repaired per water-evidence maintenance run. Property: `geopulse.boat.water-evidence.maintenance.max-users-per-run`. | Positive integer value. | Backend restart |
GEOPULSE_TIMELINE_BICYCLE_ENABLED | false | Bicycle (optional - disabled by default) Property: `geopulse.timeline.travel.classification.bicycle.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_BICYCLE_MAX_AVG_SPEED | 25.0 | Bicycle (optional - disabled by default) Property: `geopulse.timeline.travel.classification.bicycle.max_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_BICYCLE_MAX_MAX_SPEED | 35.0 | Bicycle (optional - disabled by default) Property: `geopulse.timeline.travel.classification.bicycle.max_max_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_BICYCLE_MIN_AVG_SPEED | 8.0 | Bicycle (optional - disabled by default) Property: `geopulse.timeline.travel.classification.bicycle.min_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_BOAT_ENABLED | false | Boat (optional - disabled by default). Uses water evidence; speed is only a sanity ceiling. Property: `geopulse.timeline.travel.classification.boat.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_BOAT_MAX_PLAUSIBLE_SPEED | 120.0 | Boat (optional - disabled by default). Maximum plausible speed sanity ceiling for boat classification. Property: `geopulse.timeline.travel.classification.boat.max_plausible_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_BOAT_MIN_CONTINUOUS_WATER_DISTANCE_METERS | 1000.0 | Boat (optional - disabled by default). Minimum continuous water distance required for boat classification. Property: `geopulse.timeline.travel.classification.boat.min_continuous_water_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_BOAT_MIN_WATER_DISTANCE_METERS | 2000.0 | Boat (optional - disabled by default). Minimum total water distance required for boat classification. Property: `geopulse.timeline.travel.classification.boat.min_water_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_BOAT_MIN_WATER_RATIO | 0.60 | Boat (optional - disabled by default). Minimum route water-evidence ratio required for boat classification. Property: `geopulse.timeline.travel.classification.boat.min_water_ratio`. | Decimal between 0 and 1. | Backend restart |
GEOPULSE_TIMELINE_CAR_ENABLED | true | Enables the Car label for detected motor vehicle trips. Uses the shared motor vehicle speed thresholds. Property: `geopulse.timeline.travel.classification.car.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_CAR_MIN_AVG_SPEED | 10.0 | Shared motor vehicle minimum average speed threshold used for Car and Motorcycle classification. Property: `geopulse.timeline.travel.classification.car.min_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_CAR_MIN_MAX_SPEED | 15.0 | Shared motor vehicle minimum peak speed threshold used for Car and Motorcycle classification. Property: `geopulse.timeline.travel.classification.car.min_max_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_DATA_GAP_MIN_DURATION_SECONDS | 1800 | Data Gap Detection Configuration Property: `geopulse.timeline.data_gap.min_duration_seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_DATA_GAP_STAY_OVERRIDE_ADJACENT_TOLERANCE_SECONDS | 120 | Manual Data Gap -> Stay override matching and merge tolerance (re-apply overrides after timeline rebuild/import) Property: `geopulse.timeline.data_gap_stay_override.adjacent_tolerance_seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_DATA_GAP_STAY_OVERRIDE_LOCATION_MATCH_MAX_DISTANCE_METERS | 80.0 | Manual Data Gap -> Stay override location matching fallback distance Property: `geopulse.timeline.data_gap_stay_override.location_match.max_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_DATA_GAP_STAY_OVERRIDE_MATCHING_MAX_BOUNDARY_DISTANCE_METERS | 350.0 | Manual Data Gap -> Stay override matching (re-apply overrides after timeline rebuild/import) Property: `geopulse.timeline.data_gap_stay_override.matching.max_boundary_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_DATA_GAP_STAY_OVERRIDE_MATCHING_MAX_DURATION_RATIO | 1.8 | Manual Data Gap -> Stay override matching (re-apply overrides after timeline rebuild/import) Property: `geopulse.timeline.data_gap_stay_override.matching.max_duration_ratio`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_DATA_GAP_STAY_OVERRIDE_MATCHING_MAX_TIMESTAMP_DELTA_SECONDS | 2700 | Manual Data Gap -> Stay override matching (re-apply overrides after timeline rebuild/import) Property: `geopulse.timeline.data_gap_stay_override.matching.max_timestamp_delta_seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_DATA_GAP_STAY_OVERRIDE_MATCHING_MIN_DURATION_RATIO | 0.6 | Manual Data Gap -> Stay override matching (re-apply overrides after timeline rebuild/import) Property: `geopulse.timeline.data_gap_stay_override.matching.min_duration_ratio`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_DATA_GAP_THRESHOLD_SECONDS | 10800 | Data Gap Detection Configuration Property: `geopulse.timeline.data_gap.threshold_seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_FLIGHT_ENABLED | false | Flight (optional - disabled by default) Property: `geopulse.timeline.travel.classification.flight.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_FLIGHT_MIN_AVG_SPEED | 400.0 | Flight (optional - disabled by default) Property: `geopulse.timeline.travel.classification.flight.min_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_FLIGHT_MIN_MAX_SPEED | 500.0 | Flight (optional - disabled by default) Property: `geopulse.timeline.travel.classification.flight.min_max_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_ENABLED | false | Gap Stay Inference Configuration When enabled, infers a stay instead of creating a data gap when points before/after gap are at same location Property: `geopulse.timeline.gap_stay_inference.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_IN_TRIP_LOCAL_EXCURSION_MAX_DURATION_MINUTES | 30 | Advanced gap stay inference heuristic for IN_TRIP local excursions Property: `geopulse.timeline.gap_stay_inference.in_trip_local_excursion.max_duration_minutes`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_IN_TRIP_LOCAL_EXCURSION_RADIUS_MULTIPLIER | 2.0 | Advanced gap stay inference heuristic multiplier for allowed local IN_TRIP spread Property: `geopulse.timeline.gap_stay_inference.in_trip_local_excursion.radius_multiplier`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_MAX_GAP_HOURS | 24 | Gap Stay Inference Configuration When enabled, infers a stay instead of creating a data gap when points before/after gap are at same location Property: `geopulse.timeline.gap_stay_inference.max_gap_hours`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_SPARSE_IN_TRIP_MAX_BOUNDARY_DISTANCE_METERS | 800.0 | Advanced sparse IN_TRIP gap stay inference heuristic Property: `geopulse.timeline.gap_stay_inference.sparse_in_trip.max_boundary_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_SPARSE_IN_TRIP_MAX_IMPLIED_SPEED_KMH | 1.0 | Advanced sparse IN_TRIP gap stay inference heuristic Property: `geopulse.timeline.gap_stay_inference.sparse_in_trip.max_implied_speed_kmh`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_SPARSE_IN_TRIP_MIN_BOUNDARY_DISTANCE_METERS | 150.0 | Advanced sparse IN_TRIP gap stay inference heuristic Property: `geopulse.timeline.gap_stay_inference.sparse_in_trip.min_boundary_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_SPARSE_IN_TRIP_MIN_GAP_DURATION_FLOOR_HOURS | 3 | Advanced sparse IN_TRIP gap stay inference heuristic Property: `geopulse.timeline.gap_stay_inference.sparse_in_trip.min_gap_duration_floor_hours`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_STATIONARY_BOUNDARY_IN_TRIP_ENABLED | false | Advanced stationary-boundary IN_TRIP gap stay inference heuristic Property: `geopulse.timeline.gap_stay_inference.stationary_boundary_in_trip.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_STATIONARY_BOUNDARY_IN_TRIP_MAX_BOUNDARY_DISTANCE_METERS | 100.0 | Advanced stationary-boundary IN_TRIP gap stay inference heuristic Property: `geopulse.timeline.gap_stay_inference.stationary_boundary_in_trip.max_boundary_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_STATIONARY_BOUNDARY_IN_TRIP_MAX_IMPLIED_SPEED_KMH | 1.0 | Advanced stationary-boundary IN_TRIP gap stay inference heuristic Property: `geopulse.timeline.gap_stay_inference.stationary_boundary_in_trip.max_implied_speed_kmh`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_GAP_STAY_INFERENCE_STATIONARY_BOUNDARY_IN_TRIP_MIN_GAP_DURATION_FLOOR_HOURS | 3 | Advanced stationary-boundary IN_TRIP gap stay inference heuristic Property: `geopulse.timeline.gap_stay_inference.stationary_boundary_in_trip.min_gap_duration_floor_hours`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_GAP_TRIP_INFERENCE_ENABLED | false | Gap Trip Inference Configuration When enabled, infers a trip instead of creating a data gap when distance between points exceeds threshold Useful for detecting flights, long-dis... Property: `geopulse.timeline.gap_trip_inference.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_GAP_TRIP_INFERENCE_MAX_GAP_HOURS | 24 | Gap Trip Inference Configuration When enabled, infers a trip instead of creating a data gap when distance between points exceeds threshold Useful for detecting flights, long-dis... Property: `geopulse.timeline.gap_trip_inference.max_gap_hours`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_GAP_TRIP_INFERENCE_MIN_DISTANCE_METERS | 100000 | Gap Trip Inference Configuration When enabled, infers a trip instead of creating a data gap when distance between points exceeds threshold Useful for detecting flights, long-dis... Property: `geopulse.timeline.gap_trip_inference.min_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_GAP_TRIP_INFERENCE_MIN_GAP_HOURS | 1 | Gap Trip Inference Configuration When enabled, infers a trip instead of creating a data gap when distance between points exceeds threshold Useful for detecting flights, long-dis... Property: `geopulse.timeline.gap_trip_inference.min_gap_hours`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_JOB_DELAY | 1m | Real-time Timeline Processing Configuration Property: `geopulse.timeline.job.delay`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_TIMELINE_JOB_INTERVAL | 5m | Real-time Timeline Processing Configuration Property: `geopulse.timeline.job.interval`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_TIMELINE_MOTORCYCLE_ENABLED | false | Enables the Motorcycle label for detected motor vehicle trips. Uses the shared motor vehicle speed thresholds. Property: `geopulse.timeline.travel.classification.motorcycle.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_PUBLIC_TRANSPORTATION_ENABLED | false | Enables the Public Transportation label for detected car-like trips; it does not detect a specific transit vehicle. Property: `geopulse.timeline.travel.classification.public_transportation.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_PATH_SIMPLIFICATION_ADAPTIVE | true | GPS Path Simplification Configuration Property: `geopulse.timeline.path.simplification.adaptive`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_PATH_SIMPLIFICATION_ENABLED | true | GPS Path Simplification Configuration Property: `geopulse.timeline.path.simplification.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_PATH_SIMPLIFICATION_MAX_POINTS | 100 | GPS Path Simplification Configuration Property: `geopulse.timeline.path.simplification.max_points`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_PATH_SIMPLIFICATION_TOLERANCE | 15.0 | GPS Path Simplification Configuration Property: `geopulse.timeline.path.simplification.tolerance`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_PROCESSING_THREADS | 2 | Real-time Timeline Processing Configuration Property: `geopulse.timeline.processing.thread-pool-size`. | Integer value. | Backend restart |
GEOPULSE_TIMELINE_PREFERRED_MOTORIZED_TYPE | CAR | Preferred enabled label for detected motor vehicle trips. Property: `geopulse.timeline.travel.classification.preferred_motorized_type`. | One of `CAR`, `MOTORCYCLE`, `PUBLIC_TRANSPORT`. | Backend restart |
GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_DELAY | 2m | Timeline regeneration campaign worker Property: `geopulse.timeline.regeneration-campaign.delay`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_INTERVAL | 5m | Timeline regeneration campaign worker Property: `geopulse.timeline.regeneration-campaign.interval`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_MAX_ATTEMPTS | 5 | Timeline regeneration campaign worker Property: `geopulse.timeline.regeneration-campaign.max-attempts`. | Integer value. | Backend restart |
GEOPULSE_TIMELINE_REGENERATION_CAMPAIGN_MAX_CONCURRENT_TASKS | 2 | Timeline regeneration campaign worker Property: `geopulse.timeline.regeneration-campaign.max-concurrent-tasks`. | Integer value. | Backend restart |
GEOPULSE_TIMELINE_RUNNING_ENABLED | false | Running (optional - disabled by default) Property: `geopulse.timeline.travel.classification.running.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_RUNNING_MAX_AVG_SPEED | 14.0 | Running (optional - disabled by default) Property: `geopulse.timeline.travel.classification.running.max_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_RUNNING_MAX_MAX_SPEED | 18.0 | Running (optional - disabled by default) Property: `geopulse.timeline.travel.classification.running.max_max_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_RUNNING_MIN_AVG_SPEED | 7.0 | Running (optional - disabled by default) Property: `geopulse.timeline.travel.classification.running.min_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_SHORT_DISTANCE_KM | 1.0 | Short trip distance threshold used by travel classification heuristics. Property: `geopulse.timeline.travel.classification.short_distance_km`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_ACCURACY_THRESHOLD | 60.0 | Default timeline configs. They can be overwritten by each user individually or via ENV variables Property: `geopulse.timeline.staypoint.accuracy.threshold`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_MERGE_ENABLED | true | Merge staypoints Property: `geopulse.timeline.staypoint.merge.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_MERGE_MAX_DISTANCE_METERS | 400 | Merge staypoints Property: `geopulse.timeline.staypoint.merge.max_distance_meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_MERGE_MAX_TIME_GAP_MINUTES | 15 | Merge staypoints Property: `geopulse.timeline.staypoint.merge.max_time_gap_minutes`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_MIN_ACCURACY_RATIO | 0.5 | Default timeline configs. They can be overwritten by each user individually or via ENV variables Property: `geopulse.timeline.staypoint.min_accuracy_ratio`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_MIN_DURATION_MINUTES | 7 | Default timeline configs. They can be overwritten by each user individually or via ENV variables Property: `geopulse.timeline.staypoint.min_duration_minutes`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_RADIUS_METERS | 50 | Default timeline configs. They can be overwritten by each user individually or via ENV variables Property: `geopulse.timeline.staypoint.radius_meters`. | Integer value. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_USE_VELOCITY_ACCURACY | true | Default timeline configs. They can be overwritten by each user individually or via ENV variables Property: `geopulse.timeline.staypoint.use_velocity_accuracy`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_STAYPOINT_VELOCITY_THRESHOLD | 2.5 | Default timeline configs. They can be overwritten by each user individually or via ENV variables Property: `geopulse.timeline.staypoint.velocity.threshold`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_TRAIN_ENABLED | false | Train (optional - disabled by default) Property: `geopulse.timeline.travel.classification.train.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_TRAIN_MAX_AVG_SPEED | 150.0 | Train (optional - disabled by default) Property: `geopulse.timeline.travel.classification.train.max_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_TRAIN_MAX_MAX_SPEED | 180.0 | Train (optional - disabled by default) Property: `geopulse.timeline.travel.classification.train.max_max_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_TRAIN_MAX_SPEED_VARIANCE | 15.0 | Train (optional - disabled by default) Property: `geopulse.timeline.travel.classification.train.max_speed_variance`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_TRAIN_MIN_AVG_SPEED | 30.0 | Train (optional - disabled by default) Property: `geopulse.timeline.travel.classification.train.min_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_TRAIN_MIN_MAX_SPEED | 80.0 | Train (optional - disabled by default) Property: `geopulse.timeline.travel.classification.train.min_max_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_TRIP_ARRIVAL_MIN_DURATION_SECONDS | 90 | Travel Classification Configuration Property: `geopulse.timeline.trip.arrival.min_duration_seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_TRIP_ARRIVAL_MIN_POINTS | 3 | Travel Classification Configuration Property: `geopulse.timeline.trip.arrival.min_points`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_TRIP_DETECTION_ALGORITHM | single | Trip Property: `geopulse.timeline.trip.detection.algorithm`. | String value. Follow subsystem documentation. | Backend restart |
GEOPULSE_TIMELINE_TRIP_MOVEMENT_OVERRIDE_MAX_DISTANCE_RATIO | 1.8 | Manual trip movement override matching (re-apply overrides after timeline rebuild) Property: `geopulse.timeline.trip.movement_override.matching.max_distance_ratio`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_TRIP_MOVEMENT_OVERRIDE_MAX_DURATION_RATIO | 1.8 | Manual trip movement override matching (re-apply overrides after timeline rebuild) Property: `geopulse.timeline.trip.movement_override.matching.max_duration_ratio`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_TRIP_MOVEMENT_OVERRIDE_MAX_POINT_DISTANCE_METERS | 350.0 | Manual trip movement override matching (re-apply overrides after timeline rebuild) Property: `geopulse.timeline.trip.movement_override.matching.max_point_distance_meters`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_TRIP_MOVEMENT_OVERRIDE_MAX_TIMESTAMP_DELTA_SECONDS | 2700 | Manual trip movement override matching (re-apply overrides after timeline rebuild) Property: `geopulse.timeline.trip.movement_override.matching.max_timestamp_delta_seconds`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_TRIP_MOVEMENT_OVERRIDE_MIN_DISTANCE_RATIO | 0.6 | Manual trip movement override matching (re-apply overrides after timeline rebuild) Property: `geopulse.timeline.trip.movement_override.matching.min_distance_ratio`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_TRIP_MOVEMENT_OVERRIDE_MIN_DURATION_RATIO | 0.6 | Manual trip movement override matching (re-apply overrides after timeline rebuild) Property: `geopulse.timeline.trip.movement_override.matching.min_duration_ratio`. | `true` or `false`. | Backend restart |
GEOPULSE_TIMELINE_TRIP_SUSTAINED_STOP_MIN_DURATION_SECONDS | 60 | Travel Classification Configuration Property: `geopulse.timeline.trip.sustained_stop.min_duration_seconds`. | Non-negative numeric value. | Backend restart |
GEOPULSE_TIMELINE_VIEW_ITEM_LIMIT | 150 | Timeline View Item Limit - maximum number of items to load on Timeline page For larger datasets, users will be guided to use Timeline Reports Property: `geopulse.timeline.view.item-limit`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_WALKING_MAX_AVG_SPEED | 6.0 | Walking (mandatory) Property: `geopulse.timeline.travel.classification.walking.max_avg_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TIMELINE_WALKING_MAX_MAX_SPEED | 8.0 | Walking (mandatory) Property: `geopulse.timeline.travel.classification.walking.max_max_speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TRIP_SUMMARY_PLACES_PAGE | 1 | Trip summary aggregation Property: `geopulse.trip.summary.places.page`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TRIP_SUMMARY_PLACES_PAGE_SIZE | 10000 | Trip summary aggregation Property: `geopulse.trip.summary.places.page-size`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TRIP_VISIT_MATCHING_AUTO_APPLY_ON_REGENERATION | true | Trip visit auto-matching Property: `geopulse.trip.visit-matching.auto-apply-on-timeline-regeneration`. | `true` or `false`. | Backend restart |
GEOPULSE_TRIP_VISIT_MATCHING_AUTO_THRESHOLD | 0.85 | Trip visit auto-matching Property: `geopulse.trip.visit-matching.auto-threshold`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TRIP_VISIT_MATCHING_EXACT_NAME_BOOST_DISTANCE_METERS | 120 | Trip visit auto-matching Property: `geopulse.trip.visit-matching.exact-name-boost-distance-meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TRIP_VISIT_MATCHING_MAX_DISTANCE_METERS | 400 | Trip visit auto-matching Property: `geopulse.trip.visit-matching.max-distance-meters`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_TRIP_VISIT_MATCHING_SUGGEST_THRESHOLD | 0.55 | Trip visit auto-matching Property: `geopulse.trip.visit-matching.suggest-threshold`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
Boat Water Dataset (8)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_WATER_DATASET_AUTO_IMPORT | true | Boat water dataset setup. Automatically imports the configured water-surface dataset when boat evidence is needed. Property: `geopulse.water-dataset.auto-import`. | `true` or `false`. | Backend restart |
GEOPULSE_WATER_DATASET_CONNECT_TIMEOUT_SECONDS | 30 | Boat water dataset setup. HTTP connect timeout for dataset download. Property: `geopulse.water-dataset.connect-timeout-seconds`. | Positive integer seconds. | Backend restart |
GEOPULSE_WATER_DATASET_DOWNLOAD_STALL_TIMEOUT_SECONDS | 120 | Boat water dataset setup. Maximum allowed download stall before aborting. Property: `geopulse.water-dataset.download-stall-timeout-seconds`. | Positive integer seconds. | Backend restart |
GEOPULSE_WATER_DATASET_DOWNLOAD_TIMEOUT_HOURS | 6 | Boat water dataset setup. Overall timeout for dataset download. Property: `geopulse.water-dataset.download-timeout-hours`. | Positive integer hours. | Backend restart |
GEOPULSE_WATER_DATASET_LOCAL_PATH | (empty) | Boat water dataset setup. Optional path to a pre-mounted dataset copy archive inside the backend container. Property: `geopulse.water-dataset.local-path`. | Optional readable path in backend container filesystem. | Backend restart |
GEOPULSE_WATER_DATASET_SETUP_START_TIMEOUT_MINUTES | 5 | Boat water dataset setup. Timeout while waiting for setup/import startup. Property: `geopulse.water-dataset.setup-start-timeout-minutes`. | Positive integer minutes. | Backend restart |
GEOPULSE_WATER_DATASET_SHA256 | (empty) | Boat water dataset setup. Optional SHA-256 checksum used to verify the dataset archive. Property: `geopulse.water-dataset.sha256`. | Hex SHA-256 checksum or empty to skip verification. | Backend restart |
GEOPULSE_WATER_DATASET_URL | https://github.com/tess1o/GeoPulse/releases/download/water-surfaces-v1/geopulse-water-surfaces-v1.copy.gz | Boat water dataset setup. Remote dataset archive URL; the dataset is intentionally not bundled into Flyway or the backend image. Property: `geopulse.water-dataset.url`. | Valid URL, or configure GEOPULSE_WATER_DATASET_LOCAL_PATH. | Backend restart |
GPS Filtering and Deduplication (7)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_GPS_DUPLICATE_DETECTION_ENABLED | false | Per-source duplicate detection defaults (for new sources) Property: `geopulse.gps.duplicate-detection.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GPS_DUPLICATE_DETECTION_LOCATION_TIME_THRESHOLD_MINUTES | 2 | GPS Point Duplicate Detection Configuration DEPRECATED: This setting is used for fallback when per-source threshold is NULL For new sources, use the per-source settings below in... Property: `geopulse.gps.duplicate-detection.location-time-threshold-minutes`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GPS_DUPLICATE_DETECTION_THRESHOLD_MINUTES | 2 | Per-source duplicate detection defaults (for new sources) Property: `geopulse.gps.duplicate-detection.threshold-minutes`. | Non-negative numeric value. | Backend restart |
GEOPULSE_GPS_FILTER_NEGATIVE_ACCURACY_ENABLED | true | Reject GPS points with negative accuracy values before applying per-source filtering rules Property: `geopulse.gps.filter.negative-accuracy.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GPS_FILTER_INACCURATE_DATA_ENABLED | false | GPS Filtering Configuration (per-source defaults) These values are used as defaults when creating new GPS sources Property: `geopulse.gps.filter.inaccurate-data.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_GPS_MAX_ALLOWED_ACCURACY | 100 | GPS Filtering Configuration (per-source defaults) These values are used as defaults when creating new GPS sources Property: `geopulse.gps.max-allowed-accuracy`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_GPS_MAX_ALLOWED_SPEED | 250 | GPS Filtering Configuration (per-source defaults) These values are used as defaults when creating new GPS sources Property: `geopulse.gps.max-allowed-speed`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
Weather (35)
Weather feature/provider/sampling/quota settings can also be managed from Admin Dashboard > System Settings > Weather. Saved Admin Settings values are stored in the database and take precedence over these environment defaults. By default, Weather is enabled for ongoing/current timeline activity, while historical backfill is opt-in. Scheduler cadence, target cleanup, and HTTP timeout variables are backend runtime properties and require a backend restart when changed.
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_WEATHER_ENABLED | true | Master switch for weather samples on timeline stays, trips, maps, and insights. Property: `geopulse.weather.enabled`. Default enables ongoing/current weather collection. | `true` or `false`. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_PRIMARY_PROVIDER | OPEN_METEO | Primary weather provider. Property: `geopulse.weather.primary-provider`. | OPEN_METEO or PIRATE_WEATHER. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_SECONDARY_PROVIDER | (empty) | Optional fallback weather provider. Property: `geopulse.weather.secondary-provider`. | Empty, OPEN_METEO, or PIRATE_WEATHER; must differ from primary. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_OPEN_METEO_ENABLED | true | Enable Open-Meteo as a selectable weather provider. Property: `geopulse.weather.open-meteo.enabled`. | true or false. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_OPEN_METEO_FORECAST_URL | https://api.open-meteo.com | Open-Meteo forecast/current API base URL. Property: `geopulse.weather.open-meteo.forecast-url`. | Valid URL reachable from the backend. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_OPEN_METEO_ARCHIVE_URL | https://archive-api.open-meteo.com | Open-Meteo historical archive API base URL. Property: `geopulse.weather.open-meteo.archive-url`. | Valid URL reachable from the backend. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_OPEN_METEO_API_KEY | (empty) | Optional Open-Meteo API key. Property: `geopulse.weather.open-meteo.api-key`. | Sensitive secret. Store in secret manager or Admin Settings; do not commit to VCS. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_OPEN_METEO_CONNECT_TIMEOUT_SECONDS | 5 | HTTP connect timeout for Open-Meteo requests. Property: `geopulse.weather.open-meteo.connect-timeout-seconds`. | Positive integer seconds. | Backend restart |
GEOPULSE_WEATHER_OPEN_METEO_READ_TIMEOUT_SECONDS | 15 | HTTP read timeout for Open-Meteo requests. Property: `geopulse.weather.open-meteo.read-timeout-seconds`. | Positive integer seconds. | Backend restart |
GEOPULSE_WEATHER_PIRATE_ENABLED | false | Enable Pirate Weather as a selectable weather provider. Property: `geopulse.weather.pirate.enabled`. | true or false; requires API key when enabled. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_PIRATE_BASE_URL | https://api.pirateweather.net | Pirate Weather forecast API base URL. Property: `geopulse.weather.pirate.base-url`. | Valid URL reachable from the backend. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_PIRATE_TIME_MACHINE_URL | https://timemachine.pirateweather.net | Pirate Weather historical time machine API base URL. Property: `geopulse.weather.pirate.time-machine-url`. | Valid URL reachable from the backend. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_PIRATE_API_KEY | (empty) | Pirate Weather API key. Property: `geopulse.weather.pirate.api-key`. | Sensitive secret. Store in secret manager or Admin Settings; do not commit to VCS. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_PIRATE_CONNECT_TIMEOUT_SECONDS | 5 | HTTP connect timeout for Pirate Weather requests. Property: `geopulse.weather.pirate.connect-timeout-seconds`. | Positive integer seconds. | Backend restart |
GEOPULSE_WEATHER_PIRATE_READ_TIMEOUT_SECONDS | 15 | HTTP read timeout for Pirate Weather requests. Property: `geopulse.weather.pirate.read-timeout-seconds`. | Positive integer seconds. | Backend restart |
GEOPULSE_WEATHER_ONGOING_ENABLED | true | Create weather targets for each active user's latest stay/trip. Property: `geopulse.weather.ongoing.enabled`. | `true` or `false`. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_ONGOING_INTERVAL_MINUTES | 60 | Minimum interval between ongoing weather samples. Property: `geopulse.weather.ongoing.interval-minutes`. | Integer >= 30. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_BACKFILL_ENABLED | false | Discover historical weather targets from existing timeline stays/trips. Disabled by default so past timeline locations are not sent for weather enrichment unless an admin opts in. Property: `geopulse.weather.backfill.enabled`. | `true` or `false`. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_QUOTA_DAILY_REQUEST_LIMIT | 10000 | GeoPulse-side maximum weather target attempts per UTC day. Property: `geopulse.weather.quota.daily-request-limit`. | Integer >= 0. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_QUOTA_ONGOING_RESERVE | 500 | Daily request reserve kept available for ongoing samples before backfill work can consume quota. Property: `geopulse.weather.quota.ongoing-reserve`. | Integer >= 0. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_COORDINATE_PRECISION | 2 | Decimal precision for weather coordinate buckets; lower values reuse more samples, higher values fetch more precise locations. Property: `geopulse.weather.coordinate-precision`. | Integer from 0 to 5. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_FAILED_TARGET_RETRY_ENABLED | true | Retry stale failed weather targets after cooldown. Property: `geopulse.weather.failed-target-retry.enabled`. | `true` or `false`. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_FAILED_TARGET_RETRY_COOLDOWN_HOURS | 24 | Cooldown before failed weather targets become retryable. Property: `geopulse.weather.failed-target-retry.cooldown-hours`. | Positive integer hours. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_WEATHER_TARGET_CLEANUP_JOB_CRON | 0 30 3 * * ? | Cron schedule for cleaning completed/skipped/failed weather target queue records. Property: `geopulse.weather.target-cleanup.job.cron`. | Valid Quarkus cron expression. | Backend restart |
GEOPULSE_WEATHER_TARGETS_COMPLETED_RETENTION_DAYS | 7 | Retention for completed and skipped weather target queue records. Stored weather samples are not removed by this cleanup. Property: `geopulse.weather.targets.completed-retention-days`. | Positive integer days. | Backend restart |
GEOPULSE_WEATHER_TARGETS_FAILED_RETENTION_DAYS | 30 | Retention for failed weather target queue records. Property: `geopulse.weather.targets.failed-retention-days`. | Positive integer days. | Backend restart |
GEOPULSE_WEATHER_TARGETS_IN_PROGRESS_TIMEOUT_MINUTES | 60 | Age after which locked in-progress weather targets are recovered for retry. Property: `geopulse.weather.targets.in-progress-timeout-minutes`. | Positive integer minutes. | Backend restart |
Place Discovery (POI) (10)
Place discovery suggests notable places worth visiting, with photos, when planning a trip. It reads Wikidata for the places and Wikimedia Commons for the images. Settings can also be managed from Admin Dashboard > System Settings > Place discovery. Saved Admin Settings values are stored in the database and take precedence over these environment defaults.
Both endpoints are shared public infrastructure. The place and photo caches are what keep the request volume polite, so prefer longer cache lifetimes unless you are self-hosting. Photo and data attribution is a licence obligation (ODbL for OpenStreetMap-adjacent data, per-file CC licences for Commons media) and should stay enabled.
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_POI_ENABLED | true | Master switch for place discovery and photo suggestions. Property: `geopulse.poi.enabled`. | `true` or `false`. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_USER_AGENT | GeoPulse (+https://github.com/tess1o/geopulse) | User-Agent sent to Wikidata and Commons. Property: `geopulse.poi.user-agent`. Keep it identifying your instance; an anonymous client is the one that gets rate-limited. | Non-empty string. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_LANGUAGE | en | Preferred language for place names and descriptions. Property: `geopulse.poi.language`. | Simple language tag (e.g. en, de, uk). Invalid values fall back to en. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_ATTRIBUTION_ENABLED | true | Display photo credits and data attribution. Property: `geopulse.poi.attribution.enabled`. Disabling it in your own deployment means you take on the licence obligation yourself. | `true` or `false`. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_WIKIDATA_ENDPOINT | https://query.wikidata.org | Wikidata Query Service base URL. Property: `geopulse.poi.wikidata.endpoint`. Point at a self-hosted instance to avoid public rate limits. Query is made with a bounded radius. | Absolute URL, no trailing slash. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_COMMONS_ENDPOINT | https://commons.wikimedia.org | Wikimedia Commons API base URL, used to resolve per-file credits. Property: `geopulse.poi.commons.endpoint`. | Absolute URL, no trailing slash. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_MAX_RESULTS | 40 | Upper limit on places fetched from Wikidata for one area. Property: `geopulse.poi.max-results`. Higher values cost more upstream time per uncached area. | Positive integer. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_THUMB_WIDTH | 640 | Requested photo thumbnail width in pixels. Property: `geopulse.poi.commons.thumb-width`. Commons performs the resize, so larger values mean slower fetches and more disk. | Positive integer pixels. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_CACHE_TTL_DAYS | 30 | Days place data is cached before refetching. Property: `geopulse.poi.cache.ttl-days`. The cache is global rather than per user, so one fetch serves everyone. | Positive integer days. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_POI_IMAGE_CACHE_TTL_DAYS | 90 | Days cached photo bytes are reused before refetching. Property: `geopulse.poi.cache.image-ttl-days`. | Positive integer days. | Backend restart for env changes; Admin UI changes apply through system settings |
Map Matching (18)
Map matching can use a self-hosted Valhalla instance to display road/path-snapped trip geometry. Saved values from Admin Dashboard > System Settings > Map Matching override these environment defaults for the managed settings. User profile opt-in is available only when map matching is globally enabled and Valhalla is configured.
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_TIMELINE_MAP_MATCHING_ENABLED | false | Global master switch for map matching. Property: `geopulse.timeline.map-matching.enabled`. | true or false. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_PROVIDER | valhalla | Map matching provider. Property: `geopulse.timeline.map-matching.provider`. | valhalla. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_VALHALLA_BASE_URL | (empty) | Valhalla API base URL. Property: `geopulse.timeline.map-matching.valhalla.base-url`. Required before users can enable map matching. | Valid URL reachable from the backend, or empty. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_AUTOMATIC_ENABLED | false | Automatically map-match stable new trips for all users. Property: `geopulse.timeline.map-matching.automatic.enabled`. | true or false. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_BACKFILL_ENABLED | false | Discover and map-match historical trips for all users in the background. Property: `geopulse.timeline.map-matching.backfill.enabled`. | true or false. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_AUTOMATIC_QUIET_PERIOD_MINUTES | 15 | Minutes a changed timeline must remain quiet before automatic matching starts. Property: `geopulse.timeline.map-matching.automatic.quiet-period-minutes`. | Positive integer minutes. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_CONNECT_TIMEOUT_SECONDS | 3 | HTTP connect timeout for Valhalla requests. Property: `geopulse.timeline.map-matching.connect-timeout-seconds`. | Positive integer seconds. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_READ_TIMEOUT_SECONDS | 20 | HTTP read timeout for Valhalla responses. Property: `geopulse.timeline.map-matching.read-timeout-seconds`. | Positive integer seconds. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_MAX_INPUT_POINTS | 100 | Maximum GPS points sent in each contiguous Valhalla trace chunk. Property: `geopulse.timeline.map-matching.max-input-points`. | Positive integer. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_MAX_TRIP_DURATION_HOURS | 24 | Maximum trip duration eligible for map matching. Property: `geopulse.timeline.map-matching.max-trip-duration-hours`. | Positive integer hours. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_WORKER_BATCH_SIZE | 5 | Map matching targets processed per worker run. Property: `geopulse.timeline.map-matching.worker.batch-size`. | Positive integer. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_WORKER_INTERVAL | 60s | Scheduler cadence for map matching worker ticks. Property: `geopulse.timeline.map-matching.worker.interval`. | Quarkus duration expression (for example 15s, 5m, 1h). | Backend restart |
GEOPULSE_TIMELINE_MAP_MATCHING_MAX_ATTEMPTS | 3 | Maximum attempts per map matching target. Property: `geopulse.timeline.map-matching.max-attempts`. | Positive integer. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_QUALITY_MIN_RAW_DISTANCE_METERS | 500 | Minimum raw chunk distance before matched-route quality checks apply. Property: `geopulse.timeline.map-matching.quality.min-raw-distance-meters`. | Positive integer meters. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_QUALITY_MIN_DISTANCE_COVERAGE_PERCENT | 35 | Minimum matched distance as a percent of raw chunk distance. Property: `geopulse.timeline.map-matching.quality.min-distance-coverage-percent`. | Integer from 1 to 100. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_QUALITY_MAX_DISCONTINUITY_PERCENT | 10 | Maximum unmatched gap distance between matched fragments as a percent of raw chunk distance. Property: `geopulse.timeline.map-matching.quality.max-discontinuity-percent`. | Integer from 1 to 100. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_QUALITY_MAX_SHORT_DISCONTINUITY_METERS | 100 | Minimum absolute unmatched gap allowance between matched fragments. Property: `geopulse.timeline.map-matching.quality.max-short-discontinuity-meters`. | Positive integer meters. | Backend restart for env changes; Admin UI changes apply through system settings |
GEOPULSE_TIMELINE_MAP_MATCHING_CACHE_CLEANUP_CRON | 0 45 3 * * ? | Cron schedule for cleaning detached map matching cache rows. Property: `geopulse.timeline.map-matching.cache.cleanup.cron`. | Valid Quarkus cron expression. | Backend restart |
MQTT (14)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_MQTT_BROKER_HOST | geopulse-mosquitto | MQTT Configuration (optional - only active when GEOPULSE_MQTT_ENABLED true) Property: `geopulse.mqtt.broker.host`. | String value. Follow subsystem documentation. | Backend restart |
GEOPULSE_MQTT_BROKER_PORT | 1883 | MQTT Configuration (optional - only active when GEOPULSE_MQTT_ENABLED true) Property: `geopulse.mqtt.broker.port`. | Integer in range `1-65535`. | Backend restart |
GEOPULSE_MQTT_ENABLED | false | MQTT Configuration (optional - only active when GEOPULSE_MQTT_ENABLED true) Property: `geopulse.mqtt.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_MQTT_PASSWORD | geopulse_mqtt_pass_123 | MQTT Configuration (optional - only active when GEOPULSE_MQTT_ENABLED true) Property: `geopulse.mqtt.password`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_MQTT_TLS_ENABLED | false | Enables TLS for external MQTT broker connections. Property: `geopulse.mqtt.tls.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_MQTT_TLS_PROTOCOL | TLSv1.2 | TLS protocol used by MQTT client when TLS is enabled. Property: `geopulse.mqtt.tls.protocol`. | Supported JVM TLS protocol (for example `TLSv1.2`, `TLSv1.3`). | Backend restart |
GEOPULSE_MQTT_TLS_TRUSTSTORE_PATH | (empty) | Optional truststore path for private/self-signed broker cert validation. Property: `geopulse.mqtt.tls.truststore.path`. | Readable path in backend container filesystem. | Backend restart |
GEOPULSE_MQTT_TLS_TRUSTSTORE_PASSWORD | (empty) | Truststore password for MQTT TLS. Property: `geopulse.mqtt.tls.truststore.password`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_MQTT_TLS_TRUSTSTORE_TYPE | PKCS12 | Truststore format used by MQTT TLS. Property: `geopulse.mqtt.tls.truststore.type`. | Typically `PKCS12` or `JKS`. | Backend restart |
GEOPULSE_MQTT_TLS_KEYSTORE_PATH | (empty) | Optional client certificate keystore path (required for mTLS brokers). Property: `geopulse.mqtt.tls.keystore.path`. | Readable path in backend container filesystem. | Backend restart |
GEOPULSE_MQTT_TLS_KEYSTORE_PASSWORD | (empty) | Keystore password for MQTT TLS client certificate. Property: `geopulse.mqtt.tls.keystore.password`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_MQTT_TLS_KEYSTORE_TYPE | PKCS12 | Keystore format for MQTT TLS client cert keypair. Property: `geopulse.mqtt.tls.keystore.type`. | Typically `PKCS12` or `JKS`. | Backend restart |
GEOPULSE_MQTT_TLS_INSECURE_SKIP_HOSTNAME_VERIFICATION | false | Disables TLS hostname verification for MQTT (debugging only). Property: `geopulse.mqtt.tls.insecure-skip-hostname-verification`. | `true` or `false`; keep `false` for production. | Backend restart |
GEOPULSE_MQTT_USERNAME | geopulse_mqtt_admin | MQTT Configuration (optional - only active when GEOPULSE_MQTT_ENABLED true) Property: `geopulse.mqtt.username`. | String value. Follow subsystem documentation. | Backend restart |
Notifications / Apprise (8)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_NOTIFICATIONS_APPRISE_ENABLED | false | Enables/disables external Apprise delivery for geofence alerts. Property: `geopulse.notifications.apprise.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_NOTIFICATIONS_APPRISE_API_URL | (empty) | Base URL for Apprise API service. Property: `geopulse.notifications.apprise.api-url`. | Valid URL (for example http://apprise-api:8000). | Backend restart |
GEOPULSE_NOTIFICATIONS_APPRISE_AUTH_TOKEN | (empty) | Optional API token for Apprise. Property: `geopulse.notifications.apprise.auth-token`. | Sensitive secret. Store in secret manager; do not commit to VCS. | Backend restart |
GEOPULSE_NOTIFICATIONS_APPRISE_TIMEOUT_MS | 5000 | HTTP timeout for Apprise requests in milliseconds. Property: `geopulse.notifications.apprise.timeout-ms`. | Non-negative numeric value. | Backend restart |
GEOPULSE_NOTIFICATIONS_APPRISE_VERIFY_TLS | true | Whether TLS certificate verification is enabled for Apprise calls. Property: `geopulse.notifications.apprise.verify-tls`. | `true` or `false`. | Backend restart |
GEOPULSE_NOTIFICATIONS_GEOFENCE_EVENTS_CLEANUP_ENABLED | true | Enables/disables scheduled cleanup of geofence notification events. Property: `geopulse.notifications.geofence-events.cleanup.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_NOTIFICATIONS_GEOFENCE_EVENTS_CLEANUP_SCHEDULER_CADENCE | 12h | Scheduler cadence for cleanup job ticks. Property: `geopulse.notifications.geofence-events.cleanup.scheduler-cadence`. | Quarkus duration expression (for example `30m`, `12h`, `1d`). | Backend restart |
GEOPULSE_NOTIFICATIONS_GEOFENCE_EVENTS_RETENTION_DAYS | 90 | Deletes geofence events older than this many days. Property: `geopulse.notifications.geofence-events.retention-days`. | Integer >= 1. | Backend restart |
Prometheus (9)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_PROMETHEUS_ENABLED | false | Custom Prometheus Metrics Configuration Note: The Prometheus endpoint is always available at build time. Use GEOPULSE_PROMETHEUS_ENABLED to control custom metrics collection at... Property: `geopulse.prometheus.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_PROMETHEUS_FAVORITES_ENABLED | true | Per-metric-class control (optional - all enabled by default) Property: `geopulse.prometheus.favorites.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_PROMETHEUS_GEOCODING_ENABLED | true | Per-metric-class control (optional - all enabled by default) Property: `geopulse.prometheus.geocoding.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_PROMETHEUS_GPS_POINTS_ENABLED | true | Per-metric-class control (optional - all enabled by default) Property: `geopulse.prometheus.gps-points.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_PROMETHEUS_MEMORY_ENABLED | true | Per-metric-class control (optional - all enabled by default) Property: `geopulse.prometheus.memory.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_PROMETHEUS_REFRESH_INTERVAL | 10m | Custom Prometheus Metrics Configuration Note: The Prometheus endpoint is always available at build time. Use GEOPULSE_PROMETHEUS_ENABLED to control custom metrics collection at... Property: `geopulse.prometheus.refresh-interval`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_PROMETHEUS_TIMELINE_ENABLED | true | Per-metric-class control (optional - all enabled by default) Property: `geopulse.prometheus.timeline.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_PROMETHEUS_USER_METRICS_ENABLED | true | Per-metric-class control (optional - all enabled by default) Property: `geopulse.prometheus.user-metrics.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_PROMETHEUS_WORKLOAD_ENABLED | true | Enables/disables workload timers and counters for GPS ingestion, timeline regeneration, coverage, boat/water evidence, and weather jobs. Property: `geopulse.prometheus.workload.enabled`. | `true` or `false`. | Backend restart |
Sharing and OwnTracks (2)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_OWNTRACKS_PING_TIMESTAMP_OVERRIDE | false | Property: `geopulse.owntracks.ping.timestamp.override`. | `true` or `false`. | Backend restart |
GEOPULSE_SHARE_BASE_URL | (empty) | Sharing Property: `geopulse.share.base-url`. | Valid URL. | Backend restart |
Warmup and Background Jobs (5)
| Variable | Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_BADGES_CALCULATION_DELAY | 5m | Badge Calculation Scheduler Configuration Interval for running badge calculations (uses Quarkus time expression format: 1s, 5m, 1h, etc.) Note: This setting requires application... Property: `geopulse.badges.calculation.delay`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_BADGES_CALCULATION_INTERVAL | 30m | Badge Calculation Scheduler Configuration Interval for running badge calculations (uses Quarkus time expression format: 1s, 5m, 1h, etc.) Note: This setting requires application... Property: `geopulse.badges.calculation.interval`. | Duration format (for example `1s`, `5m`, `1h`). | Backend restart |
GEOPULSE_WARMUP_ENABLED | true | Warmup Configuration Enable aggressive warmup on startup (loads real data, then forces GC) Trade-off: Longer startup time (5-8s) for safe first-request handling in 512MB containers Property: `geopulse.warmup.enabled`. | `true` or `false`. | Backend restart |
GEOPULSE_WARMUP_MAX_ITEMS | 5000 | Maximum number of items to convert to DTOs during warmup (default: 5000) Prevents memory spikes from users with excessive data (100K+ timeline items) Queries still execute fully... Property: `geopulse.warmup.max-items`. | Numeric value; keep positive unless documented otherwise. | Backend restart |
GEOPULSE_WARMUP_SAMPLE_DAYS | 30 | Number of days of timeline data to load during warmup (default: 30) Higher more thorough warmup, but longer startup Lower faster startup, but less comprehensive warmup Set to 0... Property: `geopulse.warmup.sample-days`. | Non-negative numeric value. | Backend restart |
Deployment Vars
These vars are primarily for deployment wiring and image/runtime composition.
Core Deployment and Service Wiring
| Variable | Typical Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_VERSION | 1.22.0 | Version tag used for backend/frontend image selection in Compose manifests. | Must match published image tags. | Redeploy backend/postgres services |
GEOPULSE_POSTGRES_HOST | geopulse-postgres | Postgres hostname used to build JDBC URL and service wiring. | Resolvable host inside deployment network. | Redeploy backend/postgres services |
GEOPULSE_POSTGRES_PORT | 5432 | Postgres TCP port used for service wiring. | Integer in range `1-65535`. | Redeploy backend/postgres services |
GEOPULSE_POSTGRES_DB | geopulse | Postgres database name used by app and database container initialization. | Valid PostgreSQL database identifier. | Redeploy backend/postgres services |
GEOPULSE_POSTGRES_USERNAME | geopulse-user | Database username used by backend and Postgres initialization. | Non-empty PostgreSQL role name. | Redeploy backend/postgres services |
GEOPULSE_POSTGRES_PASSWORD | change-this-secure-password | Database password used by backend and Postgres initialization. | Use strong secret; do not commit real value to VCS. | Redeploy backend/postgres services |
Predefined OIDC Provider Deployment Vars
| Variable | Typical Default | Comment | Restrictions | Restart |
|---|---|---|---|---|
GEOPULSE_OIDC_PROVIDER_GOOGLE_ENABLED | false | Enable predefined Google provider in deployment templates. | `true` or `false`. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_GOOGLE_CLIENT_ID | (empty) | Google OIDC client ID. | Required when Google provider is enabled. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_GOOGLE_CLIENT_SECRET | (empty) | Google OIDC client secret. | Sensitive secret. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_GOOGLE_DISCOVERY_URL | https://accounts.google.com/.well-known/openid-configuration | Google OIDC discovery URL. | Must be valid discovery endpoint URL. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_GENERIC_ENABLED | false | Enable predefined generic OIDC provider. | `true` or `false`. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_GENERIC_NAME | Custom OIDC | Display name for generic provider. | Non-empty label when enabled. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_GENERIC_CLIENT_ID | (empty) | Generic OIDC client ID. | Required when generic provider is enabled. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_GENERIC_CLIENT_SECRET | (empty) | Generic OIDC client secret. | Sensitive secret. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_GENERIC_DISCOVERY_URL | (empty) | Generic OIDC discovery URL. | Valid `https://.../.well-known/openid-configuration` URL. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_MICROSOFT_ENABLED | (from Helm values) | Enable predefined Microsoft provider in Helm templates. | `true` or `false`. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_MICROSOFT_CLIENT_ID | (from Helm values) | Microsoft OIDC client ID. | Required when Microsoft provider is enabled. | Backend redeploy |
GEOPULSE_OIDC_PROVIDER_MICROSOFT_CLIENT_SECRET | (from Helm values) | Microsoft OIDC client secret. | Sensitive secret. | Backend redeploy |
PostgreSQL Tuning Vars
These variables are passed to the PostgreSQL container as startup parameters.
| Variable | Standard Default | Dev Default | Comment | Restrictions | Restart |
|---|---|---|---|---|---|
GEOPULSE_POSTGRES_SHARED_BUFFERS | 256MB | 128MB | Main PostgreSQL buffer cache size. | PostgreSQL memory unit (for example `128MB`, `1GB`). | Postgres container restart |
GEOPULSE_POSTGRES_WORK_MEM | 8MB | 6MB | Memory per sort/hash operation per query node. | PostgreSQL memory unit. | Postgres container restart |
GEOPULSE_POSTGRES_MAINTENANCE_WORK_MEM | 64MB | 32MB | Memory for maintenance operations (vacuum/index build). | PostgreSQL memory unit. | Postgres container restart |
GEOPULSE_POSTGRES_EFFECTIVE_CACHE_SIZE | 1GB | 512MB | Planner estimate for available OS cache. | PostgreSQL memory unit. | Postgres container restart |
GEOPULSE_POSTGRES_MAX_WAL_SIZE | 512MB | 256MB | Maximum WAL size before checkpoints are forced. | PostgreSQL memory unit. | Postgres container restart |
GEOPULSE_POSTGRES_CHECKPOINT_TARGET | 0.9 | 0.9 | Target fraction of checkpoint interval used for checkpoint completion. | Decimal `0.0` to `1.0`. | Postgres container restart |
GEOPULSE_POSTGRES_WAL_BUFFERS | 16MB | 8MB | Memory used for WAL buffering. | PostgreSQL memory unit. | Postgres container restart |
GEOPULSE_POSTGRES_RANDOM_PAGE_COST | 1.1 | 1.1 | Planner random I/O cost estimate (often lower on SSD). | Positive decimal. | Postgres container restart |
GEOPULSE_POSTGRES_IO_CONCURRENCY | 100 | 50 | Expected concurrent disk I/O operations. | Positive integer. | Postgres container restart |
GEOPULSE_POSTGRES_AUTOVACUUM_NAPTIME | 60s | 60s | Delay between autovacuum runs. | PostgreSQL duration value. | Postgres container restart |
GEOPULSE_POSTGRES_VACUUM_SCALE_FACTOR | 0.2 | 0.2 | Tuple-update fraction threshold before autovacuum. | Decimal greater than or equal to `0`. | Postgres container restart |
GEOPULSE_POSTGRES_LOG_SLOW_QUERIES | 5000 | 1000 | Minimum duration (ms) before query is logged as slow. | Integer milliseconds. | Postgres container restart |
GEOPULSE_POSTGRES_LOG_STATEMENT | (not set) | ddl | Statement logging level for dev compose profile. | One of PostgreSQL accepted values (`none`, `ddl`, `mod`, `all`). | Postgres container restart |
GEOPULSE_POSTGRES_LOG_CHECKPOINTS | (not set) | on | Checkpoint logging flag for dev profile. | `on` or `off`. | Postgres container restart |
GEOPULSE_POSTGRES_LOG_AUTOVACUUM | (not set) | 0 | Autovacuum logging threshold in milliseconds for dev profile. | Integer milliseconds (or `-1` to disable). | Postgres container restart |
GEOPULSE_POSTGRES_TRACK_FUNCTIONS | (not set) | all | Function stats collection level for dev profile. | One of `none`, `pl`, `all`. | Postgres container restart |
Pattern-Based Vars
Dynamic OIDC Provider Pattern
Pattern: GEOPULSE_OIDC_PROVIDER_{PROVIDER}_{PROPERTY}
| Pattern Part | Comment | Restrictions |
|---|---|---|
{PROVIDER} | Provider identifier (for example GOOGLE, COMPANY, KEYCLOAK). | Uppercase letters, numbers, underscore recommended. Converted to lowercase internally. |
{PROPERTY}=ENABLED | Provider activation flag. | Must be true to activate provider. |
{PROPERTY}=CLIENT_ID | OIDC client ID. | Required when provider is enabled. |
{PROPERTY}=CLIENT_SECRET | OIDC client secret. | Required when provider is enabled; treat as secret. |
{PROPERTY}=DISCOVERY_URL | OIDC discovery endpoint. | Required when provider is enabled; valid discovery URL expected. |
{PROPERTY}=NAME | Login button display name. | Optional string. |
{PROPERTY}=ICON | Icon class or URL for provider branding. | Optional string/URL. |
{PROPERTY}=SCOPES | OAuth scopes requested during auth. | Optional, defaults to openid profile email. |