A real-time satellite data visualization system that processes and displays Himawari-8/9 satellite imagery through an interactive web interface.
For detailed installation guides, configuration, and API reference, please see our Full Documentation.
Twilight supports nine satellite composites out of the box:
true_color- Natural-color view using visible red, green, and blue bands.ir_clouds- Infrared cloud-top temperature.ash- Volcanic ash detection using thermal infrared differences.airmass- Upper-tropospheric air mass analysis.day_microphysics- Daytime cloud microphysics (particle size and phase).night_microphysics- Nighttime cloud microphysics using infrared bands.fog- Low-level fog and stratus detection.convection- Deep convection and overshooting tops.water_vapor- Differential water vapor analysis distinguishing between upper and mid-level humidity layers.
-
Configure environment:
cp .env.sample .env
-
Start core services (Infrastructure, API & Frontend):
docker compose up -d
-
Start processing workers:
docker compose -f docker-compose.workers.yml up -d
-
Access the interface: Open
http://localhost/for the public map. To use the dashboard and task management, sign in athttp://localhost/loginwith theAUTH_KEYvalue from.env(defaulttwilight-secret).
Note: The server only enqueues composite tasks automatically when
AUTO_CREATE_TASKS_ON_SYNC=true. The bundleddocker-compose.ymldoes not forward this variable, so add it to theserverservice'senvironmentlist (or create tasks throughPOST /api/tasks).
The worker system supports multiple operational modes via command-line flags (configured in the Docker Compose environment):
- Data Synchronization (
--sync): Downloads raw HSD files from NOAA S3 to local MinIO storage. - Composite Worker (
--worker): Picks tasks from the queue, generates composites, and uploads tiles.
Twilight is composed of three primary services:
/client: React-based frontend application built with TypeScript and Vite./server: Flask-based REST API serving satellite tiles, managing tasks, and generating snapshots./worker: Python processes that sync raw data from S3 and generate composites./docs: Sphinx-based documentation source files.
If you wish to run components individually for development:
# Start Redis and MinIO only
docker compose up -d redis minio
# Run Flask server (from the repository root)
uv run --package server server/app.pycd client && npm install && npm run dev# From the repository root
uv run --package worker worker/main.py --sync --worker# Run all tests
uv run --with pytest pytest
# Build documentation
make docsThis project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
