ESPAlert

🇬🇧 English | 🇪🇸 Español

Multi-risk real-time alert system for Spain

ESPAlert is an Open Source platform that aggregates weather, earthquake, traffic, and civil protection alerts into a single interactive map focused on Spain. It consumes public data from official Spanish and European sources (AEMET, IGN, DGT, MeteoAlarm) and delivers real-time updates via REST API and WebSockets.

⚠️ Legal Notice: ESPAlert is an independent Open Source community project. It is not affiliated, sponsored, or linked in any way with the Spain Government's ES-Alert system or the Directorate General of Civil Protection and Emergencies. ESPAlert consumes exclusively open public data published by AEMET, IGN, DGT, and MeteoAlarm under their respective licenses. The name "ESPAlert" refers to "España + Alertas" and does not intend to create confusion with ES-Alert.

Roadmap · Changelog · Contributing · Security · Trademark · Report Bug · 📚 Bilingual Docs · 📖 Español

Interactive Map · Live WebSockets · Meshtastic LoRa · GDPR/LOPDGDD

---

Table of Contents

• Architecture
• Quick Start
• Local Development
• Data Sources
• Environment Variables
• Production Deployment
• Roadmap
• Contributing
• License

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Turborepo                             │
│                                                              │
│  ┌──────────────┐    WebSocket / REST    ┌────────────────┐  │
│  │  apps/web    │◄──────────────────────►│   apps/api     │  │
│  │  Next.js 16  │                        │   FastAPI      │  │
│  │  MapLibre GL │                        │   Celery       │  │
│  │  shadcn/ui   │                        │   PostGIS      │  │
│  └──────────────┘                        └───────┬────────┘  │
│                                              │   │   │       │
│                              ┌───────────────┘   │   └──┐    │
│                              ▼                   ▼      ▼    │
│                         PostgreSQL            Redis  Mesh GW │
│                         + PostGIS                    (LoRa)  │
└──────────────────────────────────────────────────────────────┘

Component	Technology	Location
Web Frontend	Next.js 16, Tailwind CSS, shadcn/ui, MapLibre	apps/web
API Backend	Python 3.12, FastAPI, PostGIS, Celery, Redis	apps/api
Monorepo	Turborepo + npm workspaces	Root
Mesh Radio	Meshtastic (LoRa)	apps/api/connectors

Quick Start

Requirements: Docker 24+ and Node.js 20 LTS.

# 1. Clone the repository
git clone https://github.com/saasixx/ESPAlert.git
cd ESPAlert

# 2. Configure environment variables
cp .env.example .env
# Adjust AEMET_API_KEY if you have one (free)

# 3. Start the entire platform
docker compose up --build

Service	URL
Web App	http://localhost:3000
API REST	http://localhost:8000
Swagger	http://localhost:8000/docs

Local Development

If you prefer to run the frontend outside Docker (faster hot-reload):

# Start only infrastructure + backend
docker compose up db redis api worker beat -d

# Install monorepo dependencies
npm install

# Start frontend with Turborepo
npm run dev

Data Sources

Source	Type	Frequency	Format
AEMET OpenData	Weather alerts	5 min	CAP XML
IGN FDSN	Earthquakes	2 min	Text/CSV
DGT NAP	Traffic	5 min	DATEX2 XML
MeteoAlarm	European alerts	5 min	GeoJSON/CAP

Environment Variables

Copy .env.example to .env and adjust values. Key variables:

Variable	Description	Required
DATABASE_URL	PostgreSQL connection (asyncpg)	Yes
REDIS_URL	Redis connection	Yes
AEMET_API_KEY	AEMET OpenData key (free)	No*
JWT_SECRET	Secret for JWT tokens (≥32 chars)	Prod
ALLOWED_ORIGINS	Allowed CORS origins	Prod

* Without AEMET key, weather alerts won't be available, but other sources (IGN, DGT, MeteoAlarm) work without authentication.

Production Deployment

# On the server:
git clone https://github.com/saasixx/ESPAlert.git /opt/espalert
cd /opt/espalert
cp .env.example .env
# Edit .env with real production values!

docker compose up -d --build

The repository includes GitHub Actions in .github/workflows/ for CI and automatic SSH deployment. Configure repository secrets:

• SERVER_HOST — Server IP or domain.
• SERVER_USER — SSH user.
• SERVER_SSH_KEY — Private SSH key.

Roadmap

Check ROADMAP.md for the development plan and upcoming releases. Published changes are recorded in CHANGELOG.md.

Version	Goal	Status
v0.1.0	Public MVP — interactive map + ingestion + WebSocket	🚧 In Development
v0.2.0	Personalized Alerts — zones, filters, notifications	📋 Planned
v0.3.0	Open Platform — Flutter app, observability, i18n	📋 Planned

Contributing

Contributions are welcome! Read CONTRIBUTING.md for the workflow, conventions, and how to send a Pull Request.

New to the project? Look for issues with the good first issue label — small, well-defined tasks for beginners.

This project follows the Contributor Code of Conduct.

Security

If you discover a vulnerability, do not open a public issue. See SECURITY.md for responsible disclosure.

Credits and Dependencies

ESPAlert is built on quality free software:

• mapcn — React components for MapLibre GL (MIT)
• MapLibre GL — Interactive map engine (BSD-3-Clause)
• FastAPI — Asynchronous web framework (MIT)
• PostgreSQL + PostGIS — Geospatial database (PostgreSQL License)
• Next.js — React framework with SSR (MIT)
• Tailwind CSS — CSS utilities (MIT)
• shadcn/ui — UI components (MIT)
• Redis — In-memory cache (BSD-3-Clause)
• Celery — Distributed task queue (BSD)

Special thanks to AnmolSaini16 for mapcn and to all the Open Source projects that make ESPAlert possible.

License

Distributed under the GNU AGPL-3.0-or-later license. See LICENSE.

To protect the project's identity, the name ESPAlert, its logo, and brand elements are subject to a separate trademark policy. See TRADEMARK_POLICY.md.