Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Run with Docker
Pull the published main image from GitHub Container Registry:
docker pull ghcr.io/1337isnot1337/dopplergeist:main
The published image targets linux/amd64. Other architectures have not been
validated. To build from a repository checkout instead:
docker build --tag dopplergeist:local .
The multi-stage image builds the four native extensions with GCC. The runtime
contains Python 3.12, FFmpeg, the installed Python dependencies and browser assets.
It runs as UID/GID 10001, with the repository license and bundled notices
preserved in the installed package. Recordings, jobs, caches and historical
evidence are excluded from the build context.
Start the application
docker run --detach --init --name dopplergeist \
--publish 127.0.0.1:8765:8765 \
--mount type=volume,src=dopplergeist-jobs,dst=/data/jobs \
--mount type=volume,src=dopplergeist-cache,dst=/home/dopplergeist/.cache/dopplergeist \
ghcr.io/1337isnot1337/dopplergeist:main
Open http://127.0.0.1:8765. Docker creates the named volumes when needed.
For a local build, replace the image name with dopplergeist:local.
The jobs volume preserves uploads, results and checkpoints. The cache volume
preserves downloaded flight archives, indexes, terrain and geoid data.
Existing bind-mount directories must be writable by UID/GID 10001.
The default command is:
dopplergeist serve --host 0.0.0.0 --port 8765 --jobs /data/jobs
The service listens on the container's interfaces; the published host port stays
on loopback. Host networking is unnecessary. The unauthenticated local service's
Host and Origin checks remain enabled. Use the loopback publication shown above.
Normal non-container serve still defaults to 127.0.0.1.
Enable data downloads or use existing data
The default container has online acquisition disabled. Audio intake and discovery
remain available; historical search needs configured data and a defensible
recording-start window. To permit public downloads, append the following command
after the image name in the docker run command above:
serve --host 0.0.0.0 --port 8765 --jobs /data/jobs --online --max-runtime 14400
Downloads can require hours and tens of gigabytes. The default upload limit is
100 MiB; add --max-upload-mb 250, for example, when a larger recording is needed.
The local workflow explains timing evidence and search limits.
For an offline provider configuration, mount the JSON file read-only and append
--config /config/operator.json to the complete serve command. For example,
add this mount to docker run:
--mount type=bind,src=/absolute/path/operator.json,dst=/config/operator.json,readonly
Configuration paths must refer to paths inside the container. Mount any existing
indexes and terrain at those paths. If the configuration changes cache_root,
mount a persistent writable volume at that location as well.
Stop, restart and change ports
docker stop --time 30 dopplergeist
docker start dopplergeist
The image uses SIGINT for normal shutdown so the service closes its job manager and stops workers. Completed jobs remain readable after restart. Resume a stopped job explicitly through the UI when its checkpoint is compatible. Named volumes survive container removal; reuse the same volume names when replacing the image. The backup procedure requires a stopped, consistent job directory.
Keep host and container port numbers equal because the local Host check uses the
service port. For port 8876, use --publish 127.0.0.1:8876:8876 and append the
complete command serve --host 0.0.0.0 --port 8876 --jobs /data/jobs to the image
name. A mapping such as 8876:8765 will not pass the existing Host check.
Image versions and publication
The Docker workflow publishes ghcr.io/1337isnot1337/dopplergeist after the image
passes its runtime, HTTP, license and volume checks. A separate publishing job
loads that validated image and checks its image ID before pushing it to GHCR.
The image is transferred within the same workflow run; publication uses that
image without rebuilding it.
| Tag | Source |
|---|---|
main |
A successful push to main, or a manual run on main |
vMAJOR.MINOR.PATCH |
The matching Git tag, such as v0.1.0 |
vMAJOR.MINOR.PATCH-PRERELEASE |
The matching prerelease tag, such as v0.2.0-rc.1 |
sha-FULL_COMMIT_ID |
The complete source commit ID for every published image |
Immediately before pushing main, the workflow reads the current public Git
branch. If that branch has moved since the image was built, the run keeps its
commit tag and skips main, with the reason in the workflow summary. An
unreadable branch ref fails publication without updating main. This also
applies to reruns of older builds.
Version tags use SemVer release/prerelease syntax without +build metadata.
Image labels record the source repository, commit, version and
PolyForm-Noncommercial-1.0.0 license. A revision tag identifies the source
commit. To retain an exact built image, use the registry digest recorded in the
workflow summary: ghcr.io/1337isnot1337/dopplergeist@sha256:DIGEST.
Maintainers can publish main through Actions → Docker build, local service
and GHCR → Run workflow, selecting main. Other manually selected branches
run validation only. Pull requests and forks run without package-write
permission and cannot publish through this workflow. Publication uses the
repository's generated GITHUB_TOKEN; no registry password secret is needed.
GitHub makes a newly published GHCR package private by default. After the first
successful publication, a package administrator must set its visibility to
Public to enable the anonymous pull command above. The image's source label
links it to this repository. If an existing package rejects GITHUB_TOKEN
writes, grant this repository access under the package's Manage Actions
access settings. These package settings are separate from workflow token
permissions. See GitHub's Container registry documentation.
Verification
The Docker workflow builds the image and checks native imports, FFmpeg, GIS/audio
libraries, packaged browser assets and licenses. It checks actual HTTP access
through a bridge-published loopback port, the existing Host/Origin checks, clean
shutdown, and non-root writes that persist across containers in both volumes.
These checks generate no audio, flight tracks or scientific job results.
Publication eligibility and tag rules are also checked with
python -m unittest discover -s tests -p test_container_publish_metadata.py.