.. SPDX-FileCopyrightText: 2022 Helmholtz-Zentrum Dresden-Rossendorf (HZDR)
..
.. SPDX-License-Identifier: GPL-3.0-or-later

..
   TODO: Maybe add a new page about app_interaction module and what it does.

..
   TODO: Remove Work in Progress note.

.. note::

   This page is work in progress.

Getting Started
===============

HELIPORT is a web application built in `Python <https://www.python.org/>`_
using the `Django <https://www.djangoproject.com/>`_ web framework.
It uses `Django REST Framework <https://www.django-rest-framework.org/>`_ to provide
its API, and runs background jobs using `Celery <https://docs.celeryq.dev/>`_.
Semantic descriptions are built with
`RDFlib <https://rdflib.readthedocs.io/en/stable/>`_.

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 <https://codebase.helmholtz.cloud/heliport/heliport/>`_,
and is made up mostly of Django apps which are described in :ref:`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
<https://codebase.helmholtz.cloud/heliport/heliport.helmholtz.cloud>`_
which contains the setup for the
`HELIPORT instance in the Helmholtz Cloud <https://heliport.helmholtz.cloud/>`_.
See also :ref:`creating-a-new-heliport-config`.

.. _modules-and-apps:

Modules and Apps
----------------

The HELIPORT application code consists of various Django apps that encapsulate certain
features.
All HELIPORT Django apps are
`Python packages <https://docs.python.org/3/glossary.html#term-package>`_
and can be imported as such.
Additionally, some modules (such as :mod:`heliport.version`, or the Django management
command ``heliport-cli`` implemented in :mod:`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
:mod:`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:

.. code-block:: shell

   heliport-cli help

.. _creating-a-new-heliport-config:

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 <https://django-environ.readthedocs.io/>`_.

.. 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 <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_
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):

.. code-block:: toml

   [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.