Requirements
Hardware and software requirements for installing the ION Guard platform.
Operating system
| OS | Version | Status |
|---|---|---|
| Ubuntu | 24.04 LTS | Recommended |
| Ubuntu | 22.04 LTS | Supported |
Other Linux distributions with Docker may work, but are not officially supported.
Hardware
Minimum
| Resource | Specification |
|---|---|
| CPU | 2 cores |
| RAM | 4 GB |
| Disk | 20 GB |
| Network | Access to the local network of the BLE gateways |
Recommended (production)
| Resource | Specification |
|---|---|
| CPU | 4+ cores |
| RAM | 8 GB |
| Disk | 50 GB+ (SSD recommended) |
| Network | Gigabit Ethernet |
Disk usage grows with data retention. With the defaults (signals: 7 days, locations: 90 days), 50 GB is enough for most scenarios. Adjust RETENTION_SIGNALS_DAYS and RETENTION_LOCATIONS_DAYS as needed.
Sizing by scale
BLE signal processing is predominantly I/O bound — the disk is the main scaling axis (it grows linearly with beacons × retention time), while CPU and RAM stay nearly constant. Use SSD: InfluxDB depends on IOPS.
| Profile | Covers up to | Scenario |
|---|---|---|
| 2 vCPU + 4 GB RAM | ~200 signals/s | Most customers |
| 4 vCPU + 8 GB RAM | ~500 signals/s | Larger installations |
| 8 vCPU + 16 GB RAM | above that | Rarely needed on a single server |
Each antenna emits one MQTT packet every 5 seconds; the approximate rate is (antennas × beacons_per_antenna) / 5 signals/s. To size disk/CPU/RAM by the number of antennas, beacons, and sites, see the Server Sizing Guide (internal technical document).
Software
Installed automatically by the bootstrap
| Software | Version | Purpose |
|---|---|---|
| Docker Engine | 24+ | Container runtime |
| Docker Compose | v2 (plugin) | Container orchestration |
| curl | — | Package download |
| jq | — | JSON processing |
| gnupg | — | Package decryption |
| ufw | — | Firewall |
| logrotate | — | Log rotation |
Docker containers (managed by the platform)
| Service | Image | Version |
|---|---|---|
| MariaDB | mariadb | 11 |
| Valkey (Redis) | valkey | 8-alpine |
| InfluxDB | influxdb | 2.7 |
| Nginx | nginx | 1.27-alpine |
| PHP-FPM | Local build | PHP 8.4 |
| Mosquitto | mosquitto-go-auth | Latest |
All services run in Docker containers. There is no need to install MariaDB, Redis, InfluxDB, or Mosquitto directly on the server.
Network
Required ports
| Port | Protocol | Direction | Service |
|---|---|---|---|
| 22 | TCP | Inbound | SSH (administration) |
| 80 | TCP | Inbound | HTTP (redirect to HTTPS) |
| 443 | TCP | Inbound | HTTPS (web interface + API) |
| 8883 | TCP | Inbound | MQTT over TLS (communication with antennas/gateways) — default |
| 9001 | TCP | Inbound | MQTT WebSocket (browser debug) |
The HTTP/HTTPS and MQTT ports are configurable via .env (HTTP_PORT, HTTPS_PORT, MQTT_EXTERNAL_PORT, MQTT_WEBSOCKET_PORT). Useful when the server hosts other applications.
In recent versions, device communication with the broker uses TLS on port 8883 by default (devices must connect via TLS); port 1883 (plaintext) is reserved for isolated development brokers. Open the port defined in MQTT_EXTERNAL_PORT on the firewall according to the mode of your deployment. See Configuration → MQTT broker TLS.
Connectivity
- BLE antennas must be able to reach the server's MQTT over TLS port (8883) — Radium Gateway (Iongrade hardware) or Minew MG4C
- DigiEye gateways must be able to reach MQTT over TLS (8883) on the server
- Accelero must be able to reach MQTT over TLS (8883) and HTTPS (443) on the server
- Operators' browsers must be able to reach HTTPS (443)
DNS
Configure a DNS record (A or CNAME) pointing to the server's IP, or use the local hostname directly. The auto-generated SSL certificate includes both the hostname and the IP as SANs.
Root access
Installation requires root or sudo access to:
- Install system packages
- Configure Docker and the firewall
- Create the
iongradeuser - Register systemd services