PolarRoute-Server

Dev Status Static Badge Documentation GitHub Tag GitHub License

A web server to manage requests for meshes and routes generated using the PolarRoute and MeshiPhi libraries, implemented using Django, Celery and Django REST framework.

It currently takes vessel meshes created using MeshiPhi and serves requests for routes, which are calculated using PolarRoute.

Setup/installation

PolarRouteServer can be installed from GitHub using pip.

  • Inside a virtual environment (e.g. venv, conda, etc.) run pip install git+https://github.com/bas-amop/PolarRoute-server
  • To install a specific version append the tag, e.g. pip intall git+https://github.com/bas-amop/PolarRoute-server@v0.1.6
  • Alternatively, clone this repository with git and install from source with pip install -e .

Use docker compose for development deployment to orchestrate celery and rabbitmq alongside the django development server.

Clone this repository and run docker compose up to build and start the services.

Note: In development, meshes are not automatically ingested into the database. Follow these steps to add a mesh to the database.

  1. Make a local directory structure with mkdir -p data/mesh and copy a vessel mesh file from MeshiPhi into ./data/mesh, which is bind-mounted into the app container.
  2. Run docker compose exec app /bin/bash to open a shell inside the running app container.
  3. Run django-admin insert_mesh /usr/src/app/data/mesh/<MESH FILENAME> to insert the mesh into the database manually.

Test that the app is working using the demo tool (see Documentation). The URL of the service should be localhost:8000.

The django development server supports hot reloading and the source code is bind-mounted into the container, so changes should be reflected in the running app. Any changes to polarrouteserver.route_api.models.py will necessitate a migration to the database. To create and run migrations, run:

docker compose exec app django-admin makemigrations
docker compose exec app django-admin migrate

Optionally, Swagger can be used to serve an API schema. This is not started by default, but can be enabled by started docker compose with the --profile swagger option, e.g. docker compose --profile swagger up -d - the swagger UI will be served at localhost:80/swagger.

Using this documentation

Most of these docs are primarily aimed at developers of the package (Development) or administrators who want to deploy a copy of the server (Deployment). If you are a user/web developer who would like to request routes from PolarRoute server you should check out the Requesting Routes page and the API Reference.