digitalfabrik / opendrift-leeway-webgui

OpenDrift Leeway simulations for Search and Rescue operations (experimental!)
https://leeway.tuerantuer.org/
Apache License 2.0
12 stars 3 forks source link
celery django leeway opendrift python python3 sar search-and-rescue simulations

GitHub Workflow Status Pylint PyPi License Code style: black

About

This is a little Django web application that does an OpenDrift Leeway simulation with a set of provided parameters via a web form. The result is sent to a user via e-mail.

This is an experimental tool to help Search and Rescue operations. An experimental service is available at leeway.tuerantuer.org.

Sample output from the leeway tool (100 points, 1km radius, south of Lampedusa):

Example leeway output

Usage

Django users have to be created in the CRUD backend, available at https://leeway.example.com/admin. E-mail addresses should be added for users as they receive the result via e-mail.

The program regularly fetches incoming mails via IMAP and starts simulations from key-value-pairs in the mail subject or text body. The sender of the mail needs to have an associated account. Allowed keys via e-mail are: longitude, latitude, object_type, radius, duration, start_time. The separator between key and value is =. Key-value-pairs are separated by ; in the subject and by new lines in the text body. The date format for start date is YYYY-MM-DD HH:MM:SS.

API usage

API documentation can be found at: https://leeway.tuerantuer.org/api/docs/

Authentication can be provided in two ways:

  1. Via your session cookie, obtained from the normal login
  2. Via an authentication token, can be obtained via /api/auth/login/

Installation

Prerequisite: Python 3.8 or later is required.

  1. Clone this repository and change into the new directory:
    git clone git@github.com:digitalfabrik/opendrift-leeway-webgui.git leeway
    cd leeway
  2. Create a virtual environment outside of the project directory and activate it:
    python3 -m venv ~/.venv
    source ~/.venv/bin/activate
  3. Install the dependencies:
    pip install -e .[dev]
  4. Create minimal config file /etc/opendrift-leeway-webgui.ini to enable DEBUG mode:
    [base]
    DEBUG = True
  5. Initialize the database:
    cd opendrift_leeway_webgui
    python3 manage.py migrate
    python3 manage.py createsuperuser
  6. Build the enhanced Docker container:
    cd opendrift
    docker build -t opendrift-leeway-custom .

Development Server

  1. Switch into the cloned project and then into the opendrift_leeway_webgui subdirectory.
  2. Open two terminals:
    1. In the first terminal run:
      source ../.venv/bin/activate
      python3 manage.py runserver
    2. In the second terminal run:
      source ../.venv/bin/activate
      celery -A leeway worker -l INFO

Releasing

Run bumpver update to perform the following tasks with one command:

  1. Bump the version in pyproject.toml
  2. Create a version bump commit
  3. Create a new version tag
  4. Push the commit and tag
  5. Create a new release on PyPI via GitHub Actions

Production Server

This details the installation on Debian with Apache2 and mod_wsgi.

  1. Create target directory on the production system:
    sudo mkdir /opt/iopendrift-leeway-webgui
    sudo chown www-data:www-data /opt/opendrift-leeway-webgui
  2. Create the virtual environment:
    sudo -u www-data bash
    python3 -m venv .venv
    source .venv/bin/activate
  3. Install the application into the virtual environment:
    pip install opendrift-leeway-webgui
  4. Copy the example config file to /etc/opendrift-leeway-webgui.ini and fill in the template
  5. Install Docker and add the docker group to the www-data user.
  6. Create symlink to facilitate the Apache configuration:
    ln -s $(python -c "from opendrift_leeway_webgui.core import wsgi; print(wsgi.__file__)") .
  7. Configure Apache2 according to the example.
  8. Set up Celery worker with leeway-celery.service and start the service.