Configuration
Complete reference for the environment variables and settings of the ION Guard platform.
The .env file
The .env file is generated automatically during installation. It contains all application settings and must never be committed to version control.
Location: /home/iongrade/ionguard/.env
After editing .env, apply the changes:
cd /home/iongrade/ionguard
# Recreate containers with the new variables
./scripts/comp.sh up -d --force-recreate ionguard_php
# Clear the configuration cache
./scripts/comp.sh exec -T ionguard_php php artisan config:clear
Deployment
| Variable | Default | Description |
|---|---|---|
IONGUARD_DEPLOY | — | Deployment hostname |
FACILITY | — | Customer/facility identifier |
DEPLOY_MODE | saas | Deployment mode: saas or onpremises |
VIRTUAL_HOST | — | Virtual hostname (used by the reverse proxy) |
Network
| Variable | Default | Description |
|---|---|---|
HOST_IP | (auto) | Host IP. Auto-detected by detectHostIp.sh on every startup. Override if the machine has multiple interfaces |
MQTT_EXTERNAL_HOST | (auto) | IP/hostname that antennas and gateways use to connect to MQTT. Auto-set as HOST_IP. Override if behind NAT or a load balancer |
Application
| Variable | Default | Description |
|---|---|---|
APP_NAME | IonGuard | Application name |
APP_ENV | production | Environment: production, local, testing |
APP_KEY | (generated) | Application encryption key (base64) |
APP_DEBUG | false | Debug mode. Never true in production |
APP_URL | https://{HOST} | Application base URL |
APP_LOCALE | en | Default language (set pt_BR for Portuguese) |
APP_FALLBACK_LOCALE | en | Fallback language |
BCRYPT_ROUNDS | 12 | Bcrypt rounds for password hashing |
Logging
| Variable | Default | Description |
|---|---|---|
LOG_CHANNEL | stack | Main log channel |
LOG_STACK | daily | Stack type: daily rotation |
LOG_LEVEL | debug | Minimum level: debug, info, notice, warning, error, critical |
Database (MariaDB)
| Variable | Default | Description |
|---|---|---|
DB_CONNECTION | mariadb | Connection driver |
DB_HOST | ionguard_mariadb_{HOST} | MariaDB container hostname |
DB_PORT | 3306 | MariaDB port |
DB_DATABASE | ionguard | Database name |
DB_USERNAME | ionguard | Database user |
DB_PASSWORD | (generated) | Database password |
DATABASE_EXPOSE_PORT | (empty) | Port to expose MariaDB on the host. Leave empty in production |
Cache, Queues, and Sessions (Redis/Valkey)
| Variable | Default | Description |
|---|---|---|
CACHE_STORE | redis | Cache driver |
QUEUE_CONNECTION | redis | Queue driver |
SESSION_DRIVER | database | Session driver |
SESSION_LIFETIME | 120 | Session lifetime in minutes |
SESSION_ENCRYPT | true | Encrypts session data |
SESSION_SECURE_COOKIE | true | Session cookie over HTTPS only |
REDIS_HOST | ionguard_valkey_{HOST} | Valkey container hostname |
REDIS_PORT | 6379 | Redis port |
REDIS_PASSWORD | null | Redis password (null = no password) |
WebSocket (Reverb)
| Variable | Default | Description |
|---|---|---|
BROADCAST_CONNECTION | reverb | Broadcasting driver |
REVERB_APP_ID | (generated) | Reverb application ID |
REVERB_APP_KEY | (generated) | Reverb public key |
REVERB_APP_SECRET | (generated) | Reverb secret key |
REVERB_HOST | ionguard_reverb_{HOST} | Reverb container hostname |
REVERB_PORT | 8080 | WebSocket server port |
Note
The frontend automatically derives the WebSocket host/port/scheme from window.location at runtime. There is no need to configure VITE_REVERB_* variables.
MQTT
| Variable | Default | Description |
|---|---|---|
MQTT_ENABLED | true | Enable MQTT integration |
MQTT_HOST | ionguard_mosquitto_{HOST} | Mosquitto broker hostname |
MQTT_PORT | 8883 | MQTT port (8883 = TLS, default; 1883 only for dev broker without TLS) |
MQTT_CLIENT_ID | ionguard-listener | MQTT client ID |
MQTT_USERNAME | listener | MQTT user |
MQTT_PASSWORD | (generated) | MQTT password |
MQTT_TOPIC_PREFIX | ionguard | MQTT topic prefix |
MQTT_KEEP_ALIVE | 60 | MQTT connection keep-alive interval (seconds) |
MQTT_QOS | 1 | Quality of service for MQTT messages |
MQTT_EXTERNAL_HOST | (auto) | Host that devices use to connect (auto-detected; see the Network section) |
MQTT_EXTERNAL_PORT | 8883 | MQTT port that devices use (device-facing). See the caution below |
MQTT_WEBSOCKET_PORT | 9001 | MQTT WebSocket port exposed on the host |
MQTT broker TLS
| Variable | Default | Description |
|---|---|---|
MQTT_TLS_ENABLED | true | TLS enabled by default (fail-closed): with MQTT active and no explicit flag, the connection is made with TLS |
MQTT_TLS_CA_FILE | — | CA file with which the broker certificate was signed |
MQTT_TLS_VERIFY_PEER | true | Verifies the broker certificate |
MQTT over TLS by default (8883)
In recent versions, device communication (antennas/gateways) with the broker uses TLS on port 8883 by default — devices must connect via TLS. Port 1883 (plaintext) is reserved for an isolated development broker. When configuring the firewall and MQTT_EXTERNAL_PORT, align the port with the mode of your deployment.
InfluxDB (Time-Series)
| Variable | Default | Description |
|---|---|---|
INFLUXDB_ENABLED | true | Enable InfluxDB for BLE signals |
INFLUXDB_URL | http://ionguard_influxdb_{HOST}:8086 | InfluxDB URL |
INFLUXDB_TOKEN | (generated) | Authentication token |
INFLUXDB_ORG | iongrade | Organization in InfluxDB |
INFLUXDB_BUCKET | ionguard | Storage bucket |
Modules
| Variable | Default | Description |
|---|---|---|
MODULE_ENCRYPTION_KEY | (generated) | Key for encrypting sensitive module data (gateway credentials, tokens). Randomly generated per installation |
Important
The MODULE_ENCRYPTION_KEY is different from the release key used to package .enc modules. This key is unique per installation and protects data at runtime.
Data retention
| Variable | Default | Description |
|---|---|---|
RETENTION_SIGNALS_DAYS | 7 | Retention days for BLE signals. Applied through the InfluxDB bucket retention policy (set on container startup) |
RETENTION_LOCATIONS_DAYS | 90 | Retention days for location history (MariaDB) |
RETENTION_EVENTS_DAYS | 365 | Retention days for events |
RETENTION_AUDIT_DAYS | 365 | Retention days for audit logs |
RETENTION_BATCH_SIZE | 10000 | Batch size for data cleanup |
Where each retention is applied
Location, event, and audit retentions are cleanup jobs that run against MariaDB (config/retention.php). BLE signal retention is applied directly by the InfluxDB bucket retention policy.
Email
| Variable | Default | Description |
|---|---|---|
MAIL_MAILER | smtp | Email driver |
MAIL_HOST | — | SMTP server |
MAIL_PORT | 587 | SMTP port |
MAIL_USERNAME | — | SMTP user |
MAIL_PASSWORD | — | SMTP password |
MAIL_FROM_ADDRESS | — | Sender address |
Performance
| Variable | Default | Description |
|---|---|---|
PHP_FPM_WORKERS | 50 | Maximum number of PHP-FPM workers. Adjust according to available RAM |
TZ | America/Sao_Paulo | System timezone |
API (Sanctum tokens)
| Variable | Default | Description |
|---|---|---|
SANCTUM_TOKEN_EXPIRATION | 1440 | API token validity in minutes (1440 = 24 h) |
SANCTUM_TOKEN_PREFIX | ionguard_ | Prefix of the issued API tokens |
Ports (on-premises)
| Variable | Default | Description |
|---|---|---|
HTTP_PORT | 80 | HTTP port on the host |
HTTPS_PORT | 443 | HTTPS port on the host |
Multiple applications on the same host
If the server already hosts another application on ports 80/443, change to alternative ports (e.g., HTTP_PORT=8080, HTTPS_PORT=8443).
Application settings
Besides .env, there are PHP configuration files in app/config/ that control specific behaviors:
Location Engine (config/location.php)
Parameters for the BLE location engine (all overridable via .env):
| Variable | Default | Description |
|---|---|---|
LOCATION_WINDOW_SIZE | 15 | Window (seconds) for collecting signals for the calculation |
LOCATION_CALCULATION_INTERVAL | 5 | Interval (seconds) between location calculations |
LOCATION_MIN_SIGNALS | 2 | Minimum signals required to position a beacon |
LOCATION_RSSI_THRESHOLD_MINIMUM | -90 | Minimum RSSI (dBm) considered for zone detection |
LOCATION_HYSTERESIS_THRESHOLD | 5 | Hysteresis (dB) to avoid oscillation between zones |
LOCATION_KEEP_ALIVE_TIMEOUT | 120 | Time (seconds) without a signal to mark a device as offline |
LOCATION_BATTERY_LOW_THRESHOLD | 20 | Battery percentage that triggers a low-battery alert |
LOCATION_ESCALATION_TIMEOUT | 120 | Time (seconds) for location-related escalation |
Alerts (config/alerts.php)
| Parameter | Default | Description |
|---|---|---|
escalation.check_interval | 30 | Interval (seconds) of the job that checks alerts to escalate |
Retention (config/retention.php)
Data retention policies (also configurable via .env).
Modules (config/modules.php)
- Release key for module decryption
- Module directory
- Loading configuration