https://github.com/digitalfabrik/opendrift-leeway-webgui
OpenDrift Leeway simulations for Search and Rescue operations (experimental!)
https://github.com/digitalfabrik/opendrift-leeway-webgui
celery django leeway opendrift python python3 sar search-and-rescue simulations
Last synced: 8 months ago
JSON representation
OpenDrift Leeway simulations for Search and Rescue operations (experimental!)
- Host: GitHub
- URL: https://github.com/digitalfabrik/opendrift-leeway-webgui
- Owner: digitalfabrik
- License: apache-2.0
- Created: 2022-12-05T10:04:12.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-10-04T10:58:57.000Z (9 months ago)
- Last Synced: 2025-10-23T10:51:43.573Z (9 months ago)
- Topics: celery, django, leeway, opendrift, python, python3, sar, search-and-rescue, simulations
- Language: Python
- Homepage: https://leeway.tuerantuer.org/
- Size: 1.36 MB
- Stars: 13
- Watchers: 3
- Forks: 3
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/digitalfabrik/opendrift-leeway-webgui/actions?query=workflow%3ATests)
[](https://www.pylint.org/)
[](https://pypi.org/project/opendrift-leeway-webgui/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/psf/black)
# About
This is a little Django web application that does an [OpenDrift](https://github.com/OpenDrift/opendrift) [Leeway](https://opendrift.github.io/choosing_a_model.html) 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](https://leeway.tuerantuer.org).
Sample output from the leeway tool (100 points, 1km radius, south of Lampedusa):
# 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/](https://leeway.tuerantuer.org/api/v1/docs/#/auth/auth_login_create)
# Installation
**Prerequisite:** _Python 3.8 or later is required._
1. Clone this repository and change into the new directory:
```bash
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:
```bash
python3 -m venv ~/.venv
source ~/.venv/bin/activate
```
3. Install the dependencies:
```bash
pip install -e .[dev]
```
4. Create minimal config file `/etc/opendrift-leeway-webgui.ini` to enable `DEBUG` mode:
```dosini
[base]
DEBUG = True
```
5. Initialize the database:
```bash
cd opendrift_leeway_webgui
python3 manage.py migrate
python3 manage.py createsuperuser
```
6. Build the enhanced Docker container:
```bash
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:
```bash
source ../.venv/bin/activate
python3 manage.py runserver
```
2. In the second terminal run:
```bash
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:
```bash
sudo mkdir /opt/iopendrift-leeway-webgui
sudo chown www-data:www-data /opt/opendrift-leeway-webgui
```
2. Create the virtual environment:
```bash
sudo -u www-data bash
python3 -m venv .venv
source .venv/bin/activate
```
3. Install the application into the virtual environment:
```bash
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:
```bash
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.