Red Alert Monitoring Stack

Quick Start

# Clone and configure
git clone https://github.com/danielrosehill/Red-Alert-Monitoring-Stack-Public.git
cd Red-Alert-Monitoring-Stack-Public
cp .env.example .env
# Edit .env with your values (ALERT_AREA, MQTT_BROKER, API keys, etc.)

# Launch the stack
docker compose up -d

# Or with bundled MQTT broker:
docker compose -f docker-compose.with-broker.yml up -d

# Or for Home Assistant users (no actuator):
docker compose -f docker-compose.ha.yml up -d

Requirement: The Oref Alert Proxy must run from an Israeli IP address (geo-restricted API).

Claude Code Users

This repo includes slash commands for guided setup. Run /setup in Claude Code for a step-by-step walkthrough that configures MQTT, lights, Snapcast, and Cloudflare Tunnel.

Components

Oref Alert Proxy :8764

Polls Pikud HaOref every 3 seconds. Single source of truth for the entire stack. Dumb relay — passes raw alert data with no interpretation.

Geodash Dashboard :8083

Real-time multi-map dashboard with 1,450 polygon overlays, InfluxDB time-series storage, historical playback, and TV-optimized view.

Pushover Notifier

Push notifications when alert count crosses thresholds (50, 100, 200, 500, 1000 simultaneous areas).

Telegram Bot

On-demand intelligence bot. /sitrep generates AI situation reports using dual-model synthesis via OpenRouter.

Actuator

Physical alert outputs: TTS voice announcements via Snapcast whole-house audio, and smart light color control via MQTT. Fully customizable.

RSS Cache :8785

Polls news feeds on a schedule, serves cached articles. Used by Geodash and available for AI sitreps.

MCP Server :8786

Streamable HTTP MCP server exposing alert tools for AI agents (Claude Code, Claude Desktop, etc.).

Management UI :8888

Stack health dashboard showing status of all services with auto-refresh every 30 seconds.

Docker Compose Variants

docker-compose.yml

Use when you have an existing Mosquitto MQTT broker on your network. Set MQTT_BROKER in .env to your broker's IP.

docker compose up -d

docker-compose.with-broker.yml

Self-contained deployment with a bundled Mosquitto broker. Set MQTT_BROKER=mosquitto in .env.

docker compose -f docker-compose.with-broker.yml up -d

docker-compose.ha.yml

For Home Assistant users. Removes the actuator service — HA handles smart light and TTS automations directly by polling the proxy at http://<stack-ip>:8764/api/alerts.

docker compose -f docker-compose.ha.yml up -d

Customization

Docker Compose Override (Recommended)

The recommended way to customize the stack without modifying tracked files:

cp docker-compose.override.example.yml docker-compose.override.yml
# Edit docker-compose.override.yml with your customizations
docker compose up -d  # automatically merges override

Use overrides for: adding services (Cloudflare Tunnel, Grafana), overriding env vars, pinning image versions, setting resource limits, or adding volumes. The override file is gitignored so your changes survive git pull.

Actuator Customization

The actuator source is included at actuator/ — edit actuator.py directly to change:

Light colors (the COLORS dictionary)
TTS messages (regenerate with generate_audio.py)
MQTT payload format (Zigbee2MQTT, Tasmota, custom)
Alert thresholds and timing

Environment Variables

Variable	Required	Description
`ALERT_AREA`	Yes	Your area in Hebrew (e.g., `ירושלים - דרום`). Passed to all services.
`MQTT_BROKER`	Yes	Broker IP or `mosquitto` for bundled
`PUSHOVER_API_TOKEN`	For push	Pushover application token
`PUSHOVER_USER_KEY`	For push	Pushover user key
`TELEGRAM_BOT_TOKEN`	For bot	Bot token from @BotFather
`OPENROUTER_API_KEY`	No	For AI situation reports in Telegram
`MQTT_LIGHT_TOPICS`	No	Comma-separated MQTT topics for lights
`SNAPCAST_FIFO`	No	Path to Snapcast FIFO pipe (default: `/tmp/snapfifo`)
`TTS_ENABLED`	No	Enable/disable TTS (default: `true`)
`OPENAI_API_KEY`	No	For one-time TTS audio generation

Alert Flow

Nationwide Attack (150+ areas)

Pikud HaOref API │ polled every 3s ▼ Oref Alert Proxy (:8764) │ ├─▶ Geodash → 150 polygons turn red, stored in InfluxDB ├─▶ Pushover → "150 areas under active alert" → phone ├─▶ Actuator → Lights red + "Nationwide alert..." on Snapcast ├─▶ Telegram Bot → Awaits /sitrep → AI briefing └─▶ Management UI → All services green (or flags failures)

Direct Threat (your area)

Your area matches ALERT_AREA │ ├─▶ Actuator → Lights RED + "Seek shelter immediately" ├─▶ Geodash → Your area flashing red with siren audio │ │ ... when all-clear arrives ... │ ├─▶ Actuator → Lights GREEN + "All clear" → OFF after 2 min └─▶ Geodash → Area returns to normal

MCP Server (AI Agents)

The stack includes an MCP server for AI agent integration:

# Claude Code
claude mcp add --transport http red-alert http://localhost:8786/mcp

# Claude Desktop — add to claude_desktop_config.json:
{
  "mcpServers": {
    "red-alert": {
      "url": "http://localhost:8786/mcp"
    }
  }
}

Tool	Description
`get_current_alerts`	All currently active alerts nationwide
`get_area_alerts`	Alerts within a radius of a lat/lon point
`get_alert_history`	Recent alert history including resolved
`get_news`	Cached news articles from RSS feeds
`get_sample_payloads`	Stored sample alert payloads for dev
`get_proxy_status`	Health check of the Oref Alert Proxy

Remote Access

We recommend Cloudflare Tunnel for secure remote access to the stack. It provides HTTPS, authentication, and DDoS protection without opening router ports — and the free tier covers personal use.

Suggested subdomain pattern:

Subdomain	Service
`redalert.yourdomain.com`	Management UI (:8888)
`redalertdash.yourdomain.com`	Geodash Dashboard (:8083)
`redalertmcp.yourdomain.com`	MCP Server (:8786)

Claude Code users: run /setup-tunnel for a guided Cloudflare Tunnel setup.