Troubleshooting

Diagnostic guide for the most common IonGuard platform issues.

General diagnostics

Check container status

cd /home/iongrade/ionguard
./scripts/comp.sh ps

All containers should have status Up. If any is Exited or in a restart loop, check the logs.

Full health check

./scripts/healthcheck.sh

Checks: HTTP /up endpoint, Horizon status, and container health.

Logs for a specific service

./scripts/comp.sh logs -f ionguard_php --tail 100
./scripts/comp.sh logs -f ionguard_horizon --tail 100
./scripts/comp.sh logs -f ionguard_mosquitto --tail 100

---

Common issues

The application does not open in the browser

Symptoms: Blank page, connection error, timeout.

1. Check if nginx is running:

   ./scripts/comp.sh ps ionguard_nginx

2. Check SSL certificate:

   ./scripts/comp.sh logs ionguard_nginx --tail 20

3. Check if PHP-FPM is responding:

   ./scripts/comp.sh exec -T ionguard_php php artisan --version

4. Check firewall:

   sudo ufw status
   # Ports 80, 443 must be ALLOW

Alerts do not appear in real time

Symptoms: Alerts only appear when reloading the page.

1. Check if Reverb (WebSocket) is running:

   ./scripts/comp.sh ps ionguard_reverb

2. Check Reverb logs:

   ./scripts/comp.sh logs ionguard_reverb --tail 50

3. In the browser, open the console (F12) and check for WebSocket errors.

Beacons do not appear as "Online"

Symptoms: Registered beacons always with "Pending" or "Offline" status.

1. Check if Mosquitto is running:

   ./scripts/comp.sh ps ionguard_mosquitto

2. Check if MQTT messages are arriving:

   ./scripts/comp.sh exec -T ionguard_mosquitto \
       mosquitto_sub -h localhost -u listener -P "$(grep MQTT_PASSWORD .env | cut -d= -f2)" \
       -t "ionguard/#" -v --retained-only

3. Check if the antennas are connected to the correct broker (host, port, credentials).

4. Check MQTT worker logs:

   ./scripts/comp.sh logs ionguard_mqtt_indoor_location --tail 50

Queue jobs are not being processed

Symptoms: Reports stay as "Pending", alerts are not escalated.

1. Check if Horizon is running:

   ./scripts/comp.sh ps ionguard_horizon

2. Check the Redis queue:

   ./scripts/comp.sh exec -T ionguard_valkey redis-cli llen queues:default

3. Restart Horizon:

   ./scripts/comp.sh restart ionguard_horizon

"500 Server Error" in the interface

1. Check PHP logs:

   ./scripts/comp.sh logs ionguard_php --tail 100
   # or
   ./scripts/comp.sh exec -T ionguard_php tail -50 storage/logs/laravel.log

2. Clear cache:

   ./scripts/clearCache.sh

3. Check permissions:

   ./scripts/setPermissions.sh

Database inaccessible

1. Check if MariaDB is running:

   ./scripts/comp.sh ps ionguard_mariadb

2. Test the connection:

   ./scripts/comp.sh exec -T ionguard_mariadb \
       mariadb -u ionguard -p"$(grep DB_PASSWORD .env | cut -d= -f2)" \
       -e "SELECT 1"

3. Check disk space:

   df -h

Frontend outdated after upgrade

Symptoms: Interface shows old version or broken layout.

# Force frontend rebuild
rm -rf app/public/build
./scripts/up.sh

---

Useful commands

Command	Action
./scripts/comp.sh ps	Status of all containers
./scripts/comp.sh logs -f {container}	Real-time logs
./scripts/healthcheck.sh	Full health check
./scripts/clearCache.sh	Clear and re-optimize cache
./scripts/setPermissions.sh	Fix file permissions
./scripts/restartAllServices.sh	Restart all services
./scripts/getVersion.sh	Display current version

Support

If the issue persists after following the steps above, collect the following information for support:

1. Output of ./scripts/healthcheck.sh
2. Output of ./scripts/comp.sh ps
3. Last 100 lines of storage/logs/laravel.log
4. Current version (./scripts/getVersion.sh)
5. Detailed description of the issue and steps to reproduce