Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Add Docker image and configurable local service binding
Cinna Davis24094e17b769
diff --git a/.dockerignore b/.dockerignorenew file mode 100644index 0000000..eb86b2a--- /dev/null+++ b/.dockerignore@@ -0,0 +1,18 @@+# Send only package build inputs. Local recordings, jobs, caches and Git stay out.+**+!Dockerfile+!.dockerignore+!pyproject.toml+!setup.py+!MANIFEST.in+!README.md+!LICENSE+!licenses/+!licenses/**+!src/+!src/**+src/**/__pycache__/+src/**/*.pyc+src/**/*.so+src/**/*.pyd+src/**/*.egg-info/diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.ymlnew file mode 100644index 0000000..8adcb4a--- /dev/null+++ b/.github/workflows/docker.yml@@ -0,0 +1,103 @@+name: Docker build and local service+on:+ push:+ branches: [main]+ pull_request:+ workflow_dispatch:++permissions:+ contents: read++concurrency:+ group: docker-${{ github.ref }}+ cancel-in-progress: true++jobs:+ docker:+ runs-on: ubuntu-24.04+ timeout-minutes: 20+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ - name: Build runtime image+ run: docker build --tag dopplergeist:ci .+ - name: Check installed runtime, native modules and licenses+ run: |+ docker run --rm --entrypoint python dopplergeist:ci -m pip check+ docker run --rm --entrypoint ffmpeg dopplergeist:ci -version+ docker run --rm --entrypoint ffprobe dopplergeist:ci -version+ docker run --rm --interactive --entrypoint python dopplergeist:ci - <<'PY'+ import os+ from importlib import metadata, resources+ import soundfile+ import numpy, scipy, pandas, matplotlib, pyarrow, requests+ from pyproj import CRS+ import rasterio+ from dopplergeist import _native_ridge, _native_acoustic, _native_cpa, _native_index++ assert os.getuid() == 10001+ assert soundfile.available_formats()+ assert CRS.from_epsg(5070).is_projected+ assert rasterio.crs.CRS.from_epsg(5070).is_projected+ web = resources.files("dopplergeist.web")+ for name in ("index.html", "app.js", "style.css", "leaflet.js", "leaflet.css", "leaflet-license.txt"):+ assert web.joinpath(name).read_bytes(), name+ dist = metadata.distribution("dopplergeist")+ assert dist.metadata["License-Expression"] == "PolyForm-Noncommercial-1.0.0"+ installed = [str(path) for path in dist.files]+ assert any(path.endswith("/licenses/LICENSE") for path in installed)+ assert any(path.endswith("/licenses/licenses/MIT-legacy.txt") for path in installed)+ print("Non-root runtime, four native modules, GIS/audio libraries, assets and licenses passed.")+ PY+ - name: Check bridge HTTP and persistent volumes+ run: |+ cleanup() {+ docker logs dopplergeist-ci 2>/dev/null || true+ docker rm --force dopplergeist-ci >/dev/null 2>&1 || true+ docker volume rm dopplergeist-ci-jobs dopplergeist-ci-cache >/dev/null 2>&1 || true+ }+ trap cleanup EXIT+ docker volume create dopplergeist-ci-jobs+ docker volume create dopplergeist-ci-cache+ docker run --detach --init --name dopplergeist-ci \+ --publish 127.0.0.1:8765:8765 \+ --mount type=volume,src=dopplergeist-ci-jobs,dst=/data/jobs \+ --mount type=volume,src=dopplergeist-ci-cache,dst=/home/dopplergeist/.cache/dopplergeist \+ dopplergeist:ci+ python - <<'PY'+ import json+ import time+ from urllib.error import HTTPError, URLError+ from urllib.request import Request, urlopen++ base = "http://127.0.0.1:8765"+ for attempt in range(30):+ try:+ with urlopen(base + "/api/capabilities", timeout=2) as response:+ capabilities = json.load(response)+ break+ except (URLError, TimeoutError):+ if attempt == 29:+ raise+ time.sleep(1)+ assert capabilities["coverage"] == "conus"+ assert capabilities["online_enabled"] is False+ for path in ("/", "/app.js", "/style.css", "/leaflet.js", "/leaflet.css", "/leaflet-license.txt"):+ with urlopen(base + path, timeout=5) as response:+ assert response.status == 200 and response.read(), path+ for headers in ({"Host": "invalid.example:8765"}, {"Origin": "http://invalid.example:8765"}):+ try:+ urlopen(Request(base + "/api/capabilities", headers=headers), timeout=5)+ except HTTPError as error:+ assert error.code == 403+ else:+ raise AssertionError("Host/Origin checks must remain enabled")+ print("Bridge-published HTTP, packaged assets and existing Host/Origin checks passed.")+ PY+ docker exec dopplergeist-ci python -c 'from pathlib import Path; roots = [Path("/data/jobs"), Path.home()/".cache"/"dopplergeist"]; [(root/"container-write-check").write_text("persistent") for root in roots]'+ docker stop --time 15 dopplergeist-ci+ docker inspect --format '{{.State.ExitCode}}' dopplergeist-ci | grep -qx 0+ docker rm dopplergeist-ci+ docker run --rm --entrypoint python \+ --mount type=volume,src=dopplergeist-ci-jobs,dst=/data/jobs \+ --mount type=volume,src=dopplergeist-ci-cache,dst=/home/dopplergeist/.cache/dopplergeist \+ dopplergeist:ci -c 'from pathlib import Path; roots = [Path("/data/jobs"), Path.home()/".cache"/"dopplergeist"]; assert all((root/"container-write-check").read_text() == "persistent" for root in roots)'diff --git a/Dockerfile b/Dockerfilenew file mode 100644index 0000000..529983b--- /dev/null+++ b/Dockerfile@@ -0,0 +1,34 @@+FROM python:3.12-slim-bookworm AS build++ENV PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_NO_CACHE_DIR=1+RUN apt-get update \+ && apt-get install -y --no-install-recommends build-essential \+ && rm -rf /var/lib/apt/lists/*+WORKDIR /build+COPY pyproject.toml setup.py MANIFEST.in README.md LICENSE ./+COPY licenses/ ./licenses/+COPY src/ ./src/+RUN CC=gcc python -m pip wheel --wheel-dir /wheels .++FROM python:3.12-slim-bookworm++ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1 \+ PIP_DISABLE_PIP_VERSION_CHECK=1 PIP_NO_CACHE_DIR=1+RUN apt-get update \+ && apt-get install -y --no-install-recommends ffmpeg libsndfile1 \+ && rm -rf /var/lib/apt/lists/*+COPY --from=build /wheels /tmp/wheels+RUN python -m pip install --no-index --find-links=/tmp/wheels dopplergeist \+ && python -m pip check \+ && python -c "from dopplergeist import _native_ridge, _native_acoustic, _native_cpa, _native_index" \+ && rm -rf /tmp/wheels+RUN useradd --create-home --uid 10001 --user-group dopplergeist \+ && mkdir -p /data/jobs /home/dopplergeist/.cache/dopplergeist \+ && chown -R dopplergeist:dopplergeist /data /home/dopplergeist+WORKDIR /data+USER 10001:10001+EXPOSE 8765+# Reuse the service's KeyboardInterrupt shutdown path to stop its job workers.+STOPSIGNAL SIGINT+ENTRYPOINT ["dopplergeist"]+CMD ["serve", "--host", "0.0.0.0", "--port", "8765", "--jobs", "/data/jobs"]diff --git a/README.md b/README.mdindex d183477..bb7ffe9 100644--- a/README.md+++ b/README.md@@ -45,6 +45,10 @@ Installation builds optional acoustic, ridge, and closest-approach (CPA) accelerNative Windows execution is unverified.+For a container with FFmpeg and the native extensions included, use the+[Docker setup](docs/DOCKER.md). It includes persistent job and cache volumes and+publishes the application on a loopback port.+### Analyze from the command line```bashdiff --git a/docs/DOCKER.md b/docs/DOCKER.mdnew file mode 100644index 0000000..9c389c4--- /dev/null+++ b/docs/DOCKER.md@@ -0,0 +1,92 @@+# Run with Docker++Build from the repository checkout:++```bash+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++```bash+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 \+ dopplergeist:local+```++Open `http://127.0.0.1:8765`. Docker creates the named volumes when needed.+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:++```bash+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 `dopplergeist:local` in the `docker run` command above:++```bash+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](PRODUCT.md) 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`:++```bash+--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++```bash+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](PRODUCT.md) 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.++## 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.diff --git a/docs/PRODUCT.md b/docs/PRODUCT.mdindex d017090..f35ec9d 100644--- a/docs/PRODUCT.md+++ b/docs/PRODUCT.md@@ -49,7 +49,10 @@ tile files, archives the previous search and identities, and processes onlyunfinished work. Input, event, runtime and model checks still reject unsupportedtransitions; the upgrade does not make an inconclusive result conclusive.-The server binds to loopback. It runs one analysis process at a time, accepts up+The server binds to loopback by default. For Docker bridge networking, use+`--host 0.0.0.0` and publish the same port on the host's loopback address; see+[Docker setup](DOCKER.md). The local Host/Origin checks remain enabled.+It runs one analysis process at a time, accepts upto four pending jobs, limits uploads to 100 MiB by default, and limits analysisto one hour by default. Set `--max-upload-mb` and `--max-runtime` to change theseoperator limits. Cancellation terminates the analysis process group, includingdiff --git a/src/dopplergeist/cli.py b/src/dopplergeist/cli.pyindex df7a433..be3cc7c 100644--- a/src/dopplergeist/cli.py+++ b/src/dopplergeist/cli.py@@ -110,6 +110,8 @@ def main():serve.add_argument("--jobs",default="jobs")serve.add_argument("--config",help="Operator provider/cache/search configuration JSON")serve.add_argument("--online",action="store_true",help="Download public data to the local cache; this can require tens of gigabytes and hours")+ serve.add_argument("--host",choices=("127.0.0.1", "localhost", "0.0.0.0"),default="127.0.0.1",+ help="Bind address; use 0.0.0.0 inside a container with a loopback-published port")serve.add_argument("--port",type=listen_port,default=8765)serve.add_argument("--max-runtime",type=positive_runtime,default=3600)serve.add_argument("--max-upload-mb",type=positive_int,default=100)@@ -145,7 +147,7 @@ def main():elif args.command=="serve":from .service import servetry:- serve(args.jobs,config,port=args.port,max_runtime_s=args.max_runtime,+ serve(args.jobs,config,host=args.host,port=args.port,max_runtime_s=args.max_runtime,max_upload_bytes=args.max_upload_mb*1024*1024)except (OSError, ValueError, OverflowError) as exc:parser.error(f"Could not start local service: {exc}")diff --git a/src/dopplergeist/service.py b/src/dopplergeist/service.pyindex 76445d7..888d240 100644--- a/src/dopplergeist/service.py+++ b/src/dopplergeist/service.py@@ -1,4 +1,4 @@-"""Loopback upload/job API, sharing the automatic CLI's persistent job manager."""+"""Local upload/job API, sharing the automatic CLI's persistent job manager."""import jsonimport mimetypesfrom http.server import BaseHTTPRequestHandler, ThreadingHTTPServer@@ -15,8 +15,8 @@ class JobServer(ThreadingHTTPServer):daemon_threads = Truedef __init__(self, address, manager):- if address[0] not in {"127.0.0.1", "localhost"}:- raise ValueError("This unauthenticated local service binds to loopback only")+ if address[0] not in {"127.0.0.1", "localhost", "0.0.0.0"}:+ raise ValueError("Bind host must be 127.0.0.1, localhost or 0.0.0.0")self.manager = managersuper().__init__(address, Handler)@@ -130,11 +130,11 @@ class Handler(BaseHTTPRequestHandler):do_POST = _handle-def serve(root, config=None, *, port=8765, max_runtime_s=3600, max_upload_bytes=100*1024*1024):+def serve(root, config=None, *, host="127.0.0.1", port=8765, max_runtime_s=3600, max_upload_bytes=100*1024*1024):manager = JobManager(root, config, max_runtime_s=max_runtime_s, max_upload_bytes=max_upload_bytes)try:- with JobServer(("127.0.0.1", port), manager) as server:- print(f"DOPPLERGEIST: http://127.0.0.1:{server.server_port} (jobs: {manager.root})", flush=True)+ with JobServer((host, port), manager) as server:+ print(f"DOPPLERGEIST: http://127.0.0.1:{server.server_port} (bind: {host}; jobs: {manager.root})", flush=True)try:server.serve_forever()except KeyboardInterrupt: