Skip to content

Deployment and Operations Guide

Jump to bottom
GiZano edited this page Sep 10, 2026 · 3 revisions

Deployment & Operations Guide

This section outlines the procedures for provisioning the QuakeGuard infrastructure.

Prerequisites

  • Backend: Docker Engine & Docker Compose.
  • Edge (IoT): VS Code + PlatformIO extension.
  • Mobile: Node.js (v18+) & Expo Go app.

Backend Provisioning

  1. Navigate to backend/api.
  2. Copy the environment variables: cp .env.example .env and fill in your HiveMQ credentials.
  3. Launch the stack:
docker compose up --build -d
  1. Verify health at http://localhost:8000/health.
  2. (Optional) To enable on-premise AI emergency reports, use the ai profile — see AI Emergency Report Service.

Edge Node Flashing

  1. Navigate to firmware/esp32_code.
  2. Copy the config: cp esp32_config.env.example esp32_config.env.
  3. Update WiFi credentials, SERVER_HOST, and ENROLLMENT_TOKEN.
  4. Flash via PlatformIO.
  5. Open Serial Monitor (115200 baud) to verify successful automated registration.

Mobile Client Initialization

  1. Navigate to mobile/ and run npm install.
  2. Create a .env file mapping your backend secrets and IP:
EXPO_PUBLIC_IOT_API_KEY=your_secret_key
EXPO_PUBLIC_MOBILE_WS_TOKEN=your_ws_token
EXPO_PUBLIC_API_BASE_URL=http://YOUR_LOCAL_IP:8000
  1. Run npx expo start and scan the QR code with your smartphone.

System Certification (Stress Test)

Validate your infrastructure by simulating a 150-node seismic swarm:

cd backend/api
export API_URL="http://localhost:8000"
export NUM_SENSORS=150
python -m tests.stress_test

A successful run ends with 🏆 SYSTEM CERTIFIED.

Observability & Telemetry Dashboards

System health and network latency are continuously monitored through a Grafana container. To eliminate manual configuration, QuakeGuard leverages Grafana's automated provisioning system:

  • Data Sources: Natively mounts the TimescaleDB connection parameters.
  • Dashboards: The "Mission Control" JSON dashboard is mounted automatically.

Upon executing docker compose up -d, Grafana exposes port 3000 with a fully configured 3-tier dashboard:

  1. Live Seismograph: Aggregated real-time Magnitude (PGA) and alert tables.
  2. IoT Telemetry: Node counts, RSSI bar gauges, and ESP32 free heap stability.
  3. Backend Latency: End-to-end packet latency and ingestion throughput (Events/sec).

Testing & CI/CD Pipeline

To maintain production-grade reliability, QuakeGuard is backed by a rigorous Continuous Integration and Continuous Deployment (CI/CD) pipeline running on GitHub Actions:

  • Test Coverage: The backend is validated by 104 pytest scenarios covering ECDSA cryptography, state machine transitions, and Redis streams processing. The mobile application is covered by 23 Jest tests ensuring state management and UI resilience.
  • Quality Gates: Every pull request is automatically analyzed by SonarCloud, enforcing strict quality, reliability, and security metrics before a merge is permitted.
  • Linting & Safety: Python code is statically analyzed and formatted using Ruff, while dependencies are audited by Safety and CodeQL to prevent supply-chain attacks.

Clone this wiki locally