Getting Started

HELIPORT is a web application built in Python using the Django web framework. It uses Django REST Framework to provide its API, and runs background jobs using Celery. Semantic descriptions are built with RDFlib.

Apps and Configs

HELIPORT is comprised of reusable application code and instance configurations. The application code is what can be found in the main HELIPORT repository, and is made up mostly of Django apps which are described in Modules and Apps. Configs set up and configure a HELIPORT instance, e.g. for deployment on a site, for development, or for testing. Examples of such configs are the testing setup which can be found in testing/config/ within the HELIPORT repository, or the heliport.helmholtz.cloud repo which contains the setup for the HELIPORT instance in the Helmholtz Cloud. See also Creating a New HELIPORT Config.

Modules and Apps

The HELIPORT application code consists of various Django apps that encapsulate certain features. All HELIPORT Django apps are Python packages and can be imported as such. Additionally, some modules (such as heliport.version, or the Django management command heliport-cli implemented in heliport.manage) are not part of a Django app, and thus can be used without a fully configured instance config.

Note

Django apps have to be included correctly in the config settings in order to work.

HELIPORT’s core functionality, which is reused among other apps, is implemented in heliport.core. It includes user and project management, the interaction between HELIPORT apps, and the definition of concepts for the semantic description of digital objects.

Management Commands

Django projects contain an auto-generated script manage.py which can be used to run management commands. For convenience, HELIPORT installs this script as heliport-cli. The command heliport-cli allows you to run management tasks from HELIPORT apps as well as tasks from all other Django apps that were used to build HELIPORT.

To see a list of all available management scripts, run this command in the installed environment:

heliport-cli help

Creating a New HELIPORT Config

HELIPORT configs are equivalent to a Django “project”, i.e. the code which is created by the startproject management command. Additionally, they contain celery.py, the setup for the Celery app which runs background jobs for HELIPORT. Environment variables and secrets can be set via a .env file within the config directory. This file can be included in the settings.py using django-environ.

Note

If you decide to create a new config from scratch, it must be called heliport_config to work with the heliport-cli management command. I.e., you must execute the command django-admin startproject heliport_config. The generated manage.py script can be discarded.

We suggest creating the config within a Git repository (i.e. as a subdirectory), and adding the application code as a Git submodule along side it.

Note

The heliport modules must be added as a submodule for all asset generation to work. Installation solely as a Python dependency is currently not possible.

Then, the two modules (heliport and heliport_config) can be installed using a pyproject.toml file like so (example using Poetry with lock file and development mode):

[project]
name = "my-heliport-instance"
...

[tool.poetry]
packages = [
    { include = "heliport_config" },
]

[tool.poetry.dependencies]
heliport = {path = "./heliport", extras = ["ldap", "redis", "pgsql"], develop = true}

[build-system]
requires = ["poetry-core>=2.0.0"]
build-backend = "poetry.core.masonry.api"

The resulting directory structure should look something like this:

.
├── .git
│   └── ...
├── .gitignore
├── .gitmodules
├── README.md
├── pyproject.toml
├── poetry.lock
├── heliport
│   ├── .git
│   │   └── ...
│   └── ...
└── heliport_config
    ├── __init__.py
    ├── asgi.py
    ├── wsgi.py
    ├── celery.py
    ├── urls.py
    └── settings.py

Note

For the heliport submodule, the tag v0.9.0 or later of the HELIPORT repository must be used. Earlier versions do not support this setup.