Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

Add Docker image and configurable local service binding

Cinna Davis24094e17b769
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 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.yml
new file mode 100644
index 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/Dockerfile
new file mode 100644
index 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.md
index d183477..bb7ffe9 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,10 @@ Installation builds optional acoustic, ridge, and closest-approach (CPA) acceler
Native 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
```bash
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
new file mode 100644
index 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.md
index 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 only
unfinished work. Input, event, runtime and model checks still reject unsupported
transitions; 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 up
to four pending jobs, limits uploads to 100 MiB by default, and limits analysis
to one hour by default. Set `--max-upload-mb` and `--max-runtime` to change these
operator limits. Cancellation terminates the analysis process group, including
diff --git a/src/dopplergeist/cli.py b/src/dopplergeist/cli.py
index 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 serve
try:
- 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.py
index 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 json
import mimetypes
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -15,8 +15,8 @@ class JobServer(ThreadingHTTPServer):
daemon_threads = True
def __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 = manager
super().__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: