<!-- # ------------------------------------------------------------------------ # Licensed to the Apache Software Foundation (ASF) under one # or more contributor license agreements. See the NOTICE file # distributed with this work for additional information # regarding copyright ownership. The ASF licenses this file # to you under the Apache License, Version 2.0 (the # "License"); you may not use this file except in compliance # with the License. You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, # software distributed under the License is distributed on an # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY # KIND, either express or implied. See the License for the # specific language governing permissions and limitations # under the License. # ------------------------------------------------------------------------ --> <img src="starfall-viewer/public/StarFall.png" alt="The StarFall Patch" width="400"/>

StarFall™ – Near Real-Time Bolide Detection Engine

Overview

The StarFall software enables users to detect bolides, or fireballs, in the sky in near real-time. Bolides are a type of bright meteor which explode as they enter Earth's atmosphere.

<img src="starfall-docs/starfall-screenshot.png" alt="StarFall Screenshot" />

Introduction

StarFall is a near real-time bolide detection and alert system that was built by the Space Dynamics Laboratory while under the support of NASA's Planetary Defense Coordination Office. StarFall ingests Geostationary Lightning Mapper (GLM) L2 netCDF data from the National Oceanic and Atmospheric Administration’s (NOAA) Geostationary Operational Environmental Satellites (GOES). Although the GLM sensors were originally designed to detect lightning, they can also detect bolide signatures (see Jenniskens et al. 2018, and Rumpf et al. 2019).

While many bolide resources exist, StarFall provides users with several advantageous features. When running in continuous mode, StarFall's GLM Trigger Generator (GLM TG) pulls GLM data continuously from NOAA's gcloud to form near real-time alerts of bolide events. Although some false positives occur on a daily basis, a key component of the GLM TG is the AI/ML ROCKET model (McKinney et al. 2024, 2025, Dempster et al. 2020), which greatly reduces the number of false-positives to a managable amount for users. Additionally, the GLM TG also computes trigger parameter estimates including the time of the event (in UTC), the location of peak intensity, and the total radiated energy using Lockheed Martin continuum calibration tables for bolide events. If sufficient data is captured for stereo events, the GLM TG can also provide rough velocity estimates (speed and directional components). The web-based user interface also provides users with a way to interact and visualize the data used to form the bolide trigger and parameter estimates.

However, it should be noted that the NOAA directed GLM sensor, GOES on-board processing, and on-ground data pipelines were designed to detect lightning. Several assumptions were made during the design and development of the GLM sensor which may not be appropriate for bolide signatures. Consequently, quantitative studies of bolides using StarFall data may need to apply corrections to the parameter estimates. Known issues with bolide parameter estimates using GLM sensors have been reported on NASA's NEO-Bolide website. Relatedly, StarFall typically underestimates total energy releases as compared to USG detected events listed on JPL's CNEOS website. StarFall velocity estimates can be poor due to GLM's relatively large pixel size and depending on event entry characteristics. Also, if an event is witnessed by only one GLM sensor, a stereo altitude estimate cannot be formed, and the location of the event is made at the peak intensity for a default altitude (32 km).

This monorepo contains the following projects:

• starfall-common
• starfall-database
• starfall-server
• starfall-viewer
• glmtriggergen
• mock-event-emitter
• mock-status-server

The StarFall source code is distributed under the Apache License, version 2.0 (see the NOTICE and LICENSE files for more details).

Installation

Software Requirements

StarFall requires the following software:

| Software | Minimum Version | |---|---| | Docker CE | 28.2.2 | | Firefox | 68.12.0 |

StarFall was developed within Docker CE dev containers on WSL while using Microsoft's Dev Container extension within Visual Studio (VS) Code. This is the workspace assumed for the following instructions. It is highly recommended to replicate this workspace in order to run StarFall. Firefox is the supported browser for StarFall.

Currently Firefox browser is the best supported browser for this application. Other browsers work too but may run into occasional issues.

Running StarFall In The Production Environment

The StarFall software can run with its production environment using Docker images.

To start the application stack, run the following in a terminal:

cd StarFall
docker compose -f ./docker/docker-compose.production.yml up

A "-d" flag can be provided to run the Docker Compose command in a detached terminal:

docker compose -f ./docker/docker-compose.production.yml up -d

You can verify that all services are running with:

docker compose ps

To view logs from all containers, run the following command:

docker compose logs -f

To shut down the system and all containers, run the following command:

docker compose -f ./docker/docker-compose.production.yml down

Additional details on how to run Docker compose commands can be found on Docker’s online documentation.

Setup for Development

In order to run StarFall for development, a one-time installation of dependencies is required. This is best accomplished within the dev docker environment. To launch the dev environment inside a docker container:

1. Clone the StarFall Repository git clone git@github.com:Space-Dynamics-Laboratory/StarFall.git
2. Open the repo in VS Code cd StarFall/ code .
3. If you have the Dev Container extension installed, VS Code will detect the .devcontainer directory and prompt the user to open the repo in the container. If not, from the Command Palette (Ctrl+Shift+P) select Remote Containers: Open Folder In Container...
4. You now have access to the dev environment. For specific information about each project, see the README included in each sub directory.

For more information about developing in containers see https://code.visualstudio.com/docs/remote/containers

The one-time installation of dependencies and build of starfall-common is accomplished by running the following in a terminal in the dev environment:

npm i

cd starfall-common
npm run build

cd ..

Once the above installation and build are complete, the StarFall server and client can be started by running the following script:

./_scripts/start.py

The StarFall web-based viewer will then be accessible from a browser by navigating to http://localhost:8080.

After completing the above one-time installation process, the application can be launched at anytime using ./_scripts/start.py.

If you would like dummy data populated in the database set SKIP_INIT_4=false in the docker-compose.production.yml and the database will populate the database with mock data upon initialization. If you have already run StarFall you will need to remove the previous docker volume with docker volume rm production_dbdata for the database to trigger initialization.

SSH keys

You can install ssh keys in the .ssh/ directory so you can interact with the remote repository. If you already have ssh keys setup, simply copy them to the .ssh/ directory and make sure they are named id_rsa and id_rsa.pub. The repo is setup to ignore all files inside the .ssh/ directory so you won't accidentally commit them.

If you do not have ssh keys setup yet, there is a script in .ssh/ called keygen.sh that will generate an ssh key for you.

1. When prompted for a file in which to save the key, enter ./id_rsa.
2. Create a password
3. The public key will be printed to the screen, you will need to save it in your account settings on the remote repository software (bitbucket, gitlab, etc.).

• The keys will be stored in the .ssh/ directory which is located on the host machine so this step will only need to be performed once.
• From here the container will automatically copy your keys to the right place the next time it is rebuilt.

SSL Certs

If you would like to generate self-signed certs run the following from the root of the repo:

mkdir certs # The `certs` directory will be ignored by Git (see `.gitignore`).
cd certs/
openssl genrsa -out key.pem 2048
openssl req -new -sha256 -key key.pem -out csr.pem
openssl x509 -req -days 9999 -in csr.pem -signkey key.pem -out