Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danizd/GeoSentinel/llms.txt

Use this file to discover all available pages before exploring further.

GeoSentinel uses a single .env file at the project root to configure every service — the FastAPI backend, all ingestor scripts, the military and AIS relay microservices, and the React frontend build. Variables are loaded automatically at startup by python-dotenv in all Python processes; the frontend token is consumed by Vite at build time. In production the equivalent file is .env.production, loaded by each container via env_file: .env.production in docker-compose.prod.yml.
Never commit .env or .env.production to version control. Both files contain secrets (API keys, database credentials, OAuth2 client secrets) and are listed in .gitignore. Store production secrets in a secrets manager or as encrypted environment variables in your CI/CD system.

​
Full Template

Copy this template to .env at the project root and fill in your values: 
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/geosentinel
FIRMS_MAP_KEY=your_firms_api_key
GDELT_API_KEY=your_gdelt_api_key
ACLED_USERNAME=your_acled_email
ACLED_PASSWORD=your_acled_password
AISSTREAM_API_KEY=your_aisstream_api_key
OPENSKY_CLIENT_ID=your_opensky_client_id
OPENSKY_CLIENT_SECRET=your_opensky_client_secret
MILITARY_SOURCE=opensky
MILITARY_RELAY_URL=http://localhost:8002
AIS_RELAY_URL=http://localhost:8003
VITE_MAPBOX_TOKEN=your_mapbox_token

​
Variable Reference

​
Database

​
DATABASE_URL
string
required
PostgreSQL connection string used by SQLAlchemy (backend API) and Alembic (migrations). Must point to a PostgreSQL 16 instance with the PostGIS extension enabled.Local development: postgresql://postgres:postgres@localhost:5432/geosentinel matches the credentials in docker-compose.yml.Production: update the host, user, and password to match your production PostgreSQL container. For example: postgresql://admin:strongpassword@postgres:5432/geosentinel when the backend and database share the database_network Docker network.

​
Data Source API Keys

​
FIRMS_MAP_KEY
string
required
NASA FIRMS (Fire Information for Resource Management System) map key. Required for the run_firms.py ingestor, which polls active wildfire hotspots filtered by active AOI bounding boxes. The ingestor handles rate limiting (429 responses) with exponential backoff and filters to type 0/1 hotspots only.How to get it: Request a free map key at https://firms.modaps.eosdis.nasa.gov/api/map_key/.
​
GDELT_API_KEY
string
required
Bearer token for the GDELT Cloud Events v2 API (gdeltcloud.com/api/v2). Required for the run_gdelt.py ingestor, which fetches conflict events in 5-minute windows (up to 29 days back), maps CAMEO codes to internal categories, and deduplicates by globalEventId.How to get it: Register and generate a key at your GDELT Cloud dashboard.
​
ACLED_USERNAME
string
required
Email address registered with the Armed Conflict Location & Event Data (ACLED) project. Used together with ACLED_PASSWORD to obtain an OAuth2 Bearer token automatically. Required for the run_acled.py ingestor, which backfills 48 hours of structured conflict data and deduplicates by event_id.How to get it: Register at https://acleddata.com/myacled.
​
ACLED_PASSWORD
string
required
Password for the ACLED account identified by ACLED_USERNAME. The ingestor exchanges these credentials for a short-lived Bearer token via the ACLED OAuth2 endpoint.
​
AISSTREAM_API_KEY
string
required
API key for the AISStream WebSocket service. Required for the AIS relay microservice (services/ais_relay/) to receive real-time vessel position messages. If this key is absent or the connection drops, the relay automatically falls back to a mock data generator so the frontend AIS layer remains functional.How to get it: Register and create an API key at https://aisstream.io.

​
Military Flight Relay

​
OPENSKY_CLIENT_ID
string
required
OAuth2 client ID for the OpenSky Network API. Used by the military relay microservice (services/military_relay/) to authenticate against the OpenSky REST API and retrieve real-time state vectors for military aircraft. The relay enforces a 1 req/s rate limit to stay within OpenSky’s usage policy.How to get it: Create OAuth2 credentials in My OpenSky → Account.
​
OPENSKY_CLIENT_SECRET
string
required
OAuth2 client secret paired with OPENSKY_CLIENT_ID. Treat this like a password — never log it or expose it in error messages.How to get it: Generated alongside OPENSKY_CLIENT_ID in the OpenSky account dashboard.
​
MILITARY_SOURCE
string
default:"opensky"
Selects the data source for the military relay. Currently only opensky is supported. Reserved for future sources (e.g. ADS-B Exchange, local SDR receiver).Allowed values: opensky
​
MILITARY_RELAY_URL
string
default:"http://localhost:8002"
Base URL where the military relay microservice is listening. The FastAPI backend calls this URL to proxy GET /v1/military-flights requests. Change this in production to the container-internal address, e.g. http://military-relay:8002 if services share a Docker network.

​
AIS Vessel Relay

​
AIS_RELAY_URL
string
default:"http://localhost:8003"
Base URL where the AIS relay microservice is listening. The FastAPI backend calls this URL to proxy GET /v1/ais-vessels requests (fetching vessel positions per active AOI bounding box). Change this in production to the container-internal address, e.g. http://ais-relay:8003 if services share a Docker network.

​
Frontend

​
VITE_MAPBOX_TOKEN
string
required
Public token for Mapbox GL JS, used by the React frontend to render the interactive incident map, military flight layers, and AIS vessel layers. This token corresponds to a Mapbox account with the Maps API enabled.How to get it: Create or copy a token from the Mapbox console.
VITE_MAPBOX_TOKEN is a build-time variable. Vite inlines it into the compiled JavaScript bundle during npm run build (or during docker compose ... --build in production). It is not read from the filesystem at runtime — changing it requires a full frontend rebuild. In production, pass it explicitly on the command line:
VITE_MAPBOX_TOKEN=pk.your_token_here docker compose -f docker-compose.prod.yml up -d --build frontend

​
Variable Summary Table

VariableRequiredDefaultService
DATABASE_URL✅—Backend, Alembic
FIRMS_MAP_KEY✅—FIRMS ingestor
GDELT_API_KEY✅—GDELT ingestor
ACLED_USERNAME✅—ACLED ingestor
ACLED_PASSWORD✅—ACLED ingestor
AISSTREAM_API_KEY✅—AIS relay
OPENSKY_CLIENT_ID✅—Military relay
OPENSKY_CLIENT_SECRET✅—Military relay
MILITARY_SOURCEOptionalopenskyMilitary relay
MILITARY_RELAY_URLOptionalhttp://localhost:8002Backend
AIS_RELAY_URLOptionalhttp://localhost:8003Backend
VITE_MAPBOX_TOKEN✅ (build-time)—Frontend
ACLED data is licensed under CC BY-NC 4.0. You may only use ACLED-sourced incident data for non-commercial purposes. Do not expose raw ACLED data or ACLED-derived incidents in any commercial product or service without explicit written authorisation from ACLED. See ACLED’s terms of use for full details.

Build docs developers (and LLMs) love

Get started for freeTalk to us