Installation

Step-by-step guide to installing ION Guard on a clean Ubuntu server.

Prerequisites

Before starting, make sure the server meets the minimum requirements:

• Ubuntu 24.04 LTS or Debian 12+
• Root or sudo access
• Internet connection (to download the packages)
• DNS or hostname configured for the server

Process overview

The installation process is automated by the bootstrap.sh script, which runs the following steps:

1. System validation (Ubuntu, root, free directory)
2. Installation of system packages (curl, jq, gnupg, ufw, etc.)
3. Installation of Docker Engine + Compose plugin
4. Creation of the iongrade user (with sudo and docker access)
5. Firewall configuration (UFW)
6. Swap and logrotate configuration
7. Download and decryption of the application packages
8. Generation of the .env file with random secrets
9. Generation of configurations (nginx, mosquitto, mariadb)
10. Generation of a self-signed SSL certificate
11. Build and startup of the Docker containers
12. Execution of migrations and initial seed
13. Frontend build
14. Registration of services in systemd

Installation command

Run the following command as root on the target server:

curl -sSL https://internal.iongrade.com.br/ionguard/bootstrap.sh | sudo bash -s -- \
    --facility NOME_DA_FACILITY \
    --host ionguard.cliente.local \
    --version 0.1.0

Parameters

Parameter	Required	Description
--facility NOME	Yes	Customer identifier. Used as the package decryption key
--host HOSTNAME	Yes	DNS name or hostname for accessing the application
--version X.Y.Z	Yes	ION Guard version to install
--local-source DIR	No	Directory with local .ionguard packages (skips download). For air-gapped environments
--force	No	Overwrites an existing installation in /home/iongrade/ionguard
--ssh-key "KEY"	No	Public SSH key for access to the iongrade user

Air-gapped installation (no internet)

For environments without internet access, copy the packages to the server and use --local-source:

# On the server with internet — download the packages
wget https://internal.iongrade.com.br/ionguard/bootstrap.sh

# Copy bootstrap.sh and the .ionguard packages to the target server
scp bootstrap.sh 0.1.0.ionguard deploy.ionguard usuario@servidor:/tmp/

# On the target server
sudo bash /tmp/bootstrap.sh \
    --facility NOME_DA_FACILITY \
    --host ionguard.cliente.local \
    --version 0.1.0 \
    --local-source /tmp

What is created

After installation, the following structure is created:

/home/iongrade/ionguard/
├── app/                    # Laravel application code
├── deploy/                 # Docker scripts and configurations
│   ├── scripts/            # Operational scripts
│   ├── docker/             # Dockerfiles and configs
│   └── systemd/            # systemd units
├── modules.json            # List of active compose files
├── .env                    # Environment variables (auto-generated)
├── backup/                 # Backup directory
└── logs/                   # Application logs

Docker containers

Container	Image	Port	Function
ionguard_nginx	nginx:1.27-alpine	80, 443	Reverse proxy with HTTPS
ionguard_php	Local build (PHP 8.4 FPM)	—	Laravel application
ionguard_mariadb	mariadb:11	—	Database
ionguard_valkey	valkey:8-alpine	—	Cache, queues, and sessions
ionguard_influxdb	influxdb:2.7	—	Time-series (BLE signals)
ionguard_mosquitto	mosquitto-go-auth	1883, 9001	MQTT broker
ionguard_horizon	Local build	—	Queue workers
ionguard_scheduler	Local build	—	Scheduled tasks
ionguard_reverb	Local build	8080	WebSocket

systemd services

• ionguard-autostart.service — Starts all containers automatically on server boot
• ionguard-inotify.service — Watcher for remote commands

Firewall (UFW)

Ports opened automatically:

Port	Protocol	Service
22	TCP	SSH
80	TCP	HTTP (redirect to HTTPS)
443	TCP	HTTPS
1883	TCP	MQTT
9001	TCP	MQTT WebSocket

First access

After installation, the script displays a banner with the credentials:

╔══════════════════════════════════════╗
║       ION Guard v0.1.0 instalado     ║
╠══════════════════════════════════════╣
║  URL:    https://ionguard.cliente.local
║  Email:  dev@iongrade.com.br
║  Senha:  (exibida no terminal)
╚══════════════════════════════════════╝

Important

The administrator's initial password is displayed only in the terminal during installation. Note it down and change it immediately after your first login.

The initial user is created with the Platform Admin profile, which has full access to the system. See Access Profiles to understand the different permission levels.

Idempotency

The bootstrap script is safe to re-run:

• If Docker is already installed → skips installation
• If the iongrade user already exists → skips creation (re-applies the SSH key if provided)
• If the installation directory already exists → error (use --force to overwrite)
• If swap is already configured → skips
• If the SSL certificate already exists → skips

Post-installation verification

After installation, check the system state:

# Check running containers
cd /home/iongrade/ionguard
./scripts/comp.sh ps

# Check health check
./scripts/healthcheck.sh

# Check logs
./scripts/comp.sh logs -f ionguard_php --tail 50

Next steps

• Configuration — Adjust environment variables
• Module Installation — Install the IndoorLocation, DigiEye, Accelero modules
• Getting Started — Start using the platform