Configuration Reference

Introduction

• The main.config.json file is located in the config/ directory of the project (or /opt/safecall/config/ in production). Legacy installations with the file in the root directory are automatically migrated on first run.
• Only options that differ from defaults need to be in the config file. Missing options are filled from config/defaults.ts at startup and written back to the file.
• The web (frontend) service does not have any configuration options of its own but consumes the config of other services in its build process. The entire configuration file is never included in the build process to avoid leaking sensitive information.
• This file is generated automatically by the deployment installer or setup wizard.
• After deploying the app, change the password of the default admin user to something secure using the web interface.

Features

The server_features array controls which subsystems are started. Available features:

Feature	Description
"bridge"	Zabbix MQTT bridge (can run standalone or alongside others)
"navigation"	Indoor navigation (maps, zones, tracking canvas)
"alerting"	Emergency alerting / SOS / KISS integration
"rtls"	Real-time location system (zone prediction, tracking algorithms)
"sensors"	Sensor data collection, storage, and alerts dashboard
"safecall"	Legacy alias — expands to all non-bridge features

Common configurations:

• Full server + bridge: ["bridge", "safecall"]
• Bridge only (e.g. on Zabbix machine): ["bridge"]
• Navigation only: ["navigation"]
• Custom subset: ["navigation", "alerting"]

Minimal Config Example

Only server_id and server_features are truly required. Everything else has defaults:

{
  "server_id": "PRD001",
  "server_features": ["navigation", "alerting"],
  "server_http_port": 8088,
  "server_mqtt_url": "mqtt://10.0.0.5:1883",
  "server_mqtt_user": "myuser",
  "server_mqtt_pass": "mypass"
}

Bridge-only installations need even less:

{
  "server_id": "BRG001",
  "server_features": ["bridge"],
  "server_bridge_server_url": "http://10.0.0.10:8088/",
  "server_bridge_zabbix_host": "localhost"
}

All Configurable Options

Core

Key	Default	Description
server_id	"TST000"	Unique server identifier
server_features	["bridge", "safecall"]	Features to enable (see above)
server_mode	"prod"	Server mode: "prod" or "debug"
server_http_port	8088	Port for the HTTP server
server_db_path	"db/safecall.db"	Path to the SQLite database file
server_url_prod	"/"	Production URL of the server
server_url_ws	"/ws"	WebSocket URL

Auth / Credentials

Key	Default	Description
server_credentials_default_email	(from brand)	Default admin email
server_credentials_default_password	"changeme"	Default admin password
server_auth_jwt_issuer	(from brand)	JWT issuer
server_auth_jwt_audience	(from brand)	JWT audience
server_auth_jwt_expiry	"8h"	JWT token expiry duration
server_mobile_api_key	"change-me-with-safecall-config-regen-mobile-key"	Shared secret used only for mobile navigation endpoint authentication; regenerate with safecall config regen-mobile-key

Brand-dependent defaults

The JWT issuer, audience, default admin email, and features are derived from the active brand at runtime (see Whitelabel / Brands). This ensures the server defaults always match the values baked into the frontend during a release build. You only need to override these if your deployment uses different values.

MQTT

Key	Default	Description
server_mqtt_url	"mqtt://localhost:1883"	MQTT broker URL
server_mqtt_user	"safecall"	MQTT broker username
server_mqtt_pass	"safecall"	MQTT broker password

Bridge (only used when "bridge" feature is enabled)

Key	Default	Description
server_bridge_server_url	"http://localhost:8088/"	URL of the SafeCall server
server_bridge_zabbix_host	"localhost"	Hostname of the Zabbix server
server_bridge_zabbix_port	10051	Port of the Zabbix server
server_bridge_endpoint_beacon	"lld/beacons"	REST endpoint for beacons
server_bridge_endpoint_gateway	"lld/gateways"	REST endpoint for gateways
server_bridge_delay_beacon	300	Delay between beacon updates (seconds)
server_bridge_delay_gateway	300	Delay between gateway updates (seconds)
server_bridge_cache_update_interval	3600	Interval for refreshing cache (seconds)

KISS / Alerting (only used when "alerting" feature is enabled)

Key	Default	Description
server_kiss_url_base	""	Base URL for KISS API
server_kiss_url_path_login	"/api/Mobile/LoginUser"	Path for KISS login endpoint
server_kiss_url_path_convene	"/api/Mobile/ExecuteConveneByRule"	Path for KISS convene endpoint
server_kiss_credentials_username	""	Username for KISS API
server_kiss_credentials_password	""	Password for KISS API

Performance / Devices

Key	Default	Description
server_devices_cache_sync_interval	300	Interval for devices cache sync (seconds)
server_perf_memory_threshold	512	Memory threshold in MB for leak detection

Diagnostics (Debug Mode)

When server_mode is set to "debug" (or the binary is started with --debug), the server writes periodic JSON snapshot files containing system metrics, MQTT throughput, tracking algorithm performance, WebSocket stats, and memory estimates. See Server Diagnostics for full details.

Key	Default	Description
server_debug_snapshot_interval	300	Seconds between diagnostic snapshots
server_debug_log_dir	"logs/diagnostics"	Directory for snapshot files (relative to binary location)
server_debug_max_files	288	Maximum snapshot files to retain (288 = 24h at 5min intervals)
server_log_verbosity	"normal"	Application audit log verbosity: "none", "normal", "verbose"

Gateway LuCI (admin UI gateway configuration tool)

Key	Default	Description
server_gateway_luci_username	"admin"	Default LuCI username for apply / fetch-preset when the UI does not override
server_gateway_luci_password	"admin"	Default LuCI password (set in deployment config)
server_gateway_luci_http_transport	"fetch"	Outbound HTTP client: "fetch" (Bun) or "curl" (requires curl on server PATH). Use "curl" if gateways fail with fetch but work with manual curl
server_gateway_luci_timeout_sec	30	Timeout per LuCI request (login and admin endpoints)
server_gateway_scan_default_subnet	""	Default CIDR for subnet scan when the UI leaves subnet empty; empty string derives a /24 from the host’s first non-internal IPv4

Notifications

Key	Default	Description
server_ntfy_enabled	true	Enable ntfy push notifications
server_ntfy_server_url	https://notify.${active_brand.company_domain}	Base ntfy server URL used when publishing push notifications

The dashboard shows the recommended ntfy subscriptions. Topic names are prefixed with server_id:

• ${server_id}-sensors — sensor alerts and sensor not-seen alerts
• ${server_id}-sos — panic alerts and panic not-seen alerts
• ${server_id}-watches — watch button push alerts
• ${server_id}-batteries — low battery alerts

Grafana datasource API notes:

• SafeCall exposes /grafana/search, /grafana/metrics, and /grafana/query for Grafana JSON datasource integrations.
• Loopback requests (127.0.0.1 / ::1) can use these endpoints without JWT.
• Non-loopback requests must still provide a valid SafeCall JWT.
• See Grafana Setup for step-by-step configuration.

Log Verbosity Policy

The server_log_verbosity key controls writes to the SQL logs table.

• none: disable app-level log writes.
• normal: record operational/audit changes.
• verbose: include everything from normal plus high-frequency/operator activity.

Current classification rules:

• Normal
  • Entity create/update/delete (users, beacons, gateways, locations, maps, floors, nodes, edges, navigation tokens).
  • Settings changes via PATCH /settings.
• Verbose
  • User login events.
  • Tool usage events (Debug Device, Gateway ID, Placement Planner interactions).

Guidance for future features:

• If an action mutates persisted state or system behavior, classify as Normal.
• If an action is diagnostic, exploratory, or high-frequency UI/tool usage, classify as Verbose.
• Never include secret values (passwords, tokens, API keys) in log messages.

Whitelabel / Brands

The build system supports multiple brand profiles. Set the SAFECALL_BRAND environment variable or use --brand=<name> when building:

# Build for SafeCall (default)
bash scripts/build/server.sh --brand=safecall

# Build for NavBeacon (navigation only, Bleuvista branding)
bash scripts/build/server.sh --brand=navbeacon

Brand definitions live in config/brands/. Each brand specifies product name, company, default features, update server URL, and other branding details.

Several configuration defaults are derived from the active brand so that a release build's baked-in values (JWT issuer/audience, default features, admin email) always match the server's runtime defaults:

Config key	Brand field
server_features	default_features
server_credentials_default_email	default_admin_email
server_auth_jwt_issuer	auth_issuer
server_auth_jwt_audience	auth_audience

This means a fresh deployment with default config will work out of the box — no need to manually align JWT or feature settings with the brand.