<!--
SPDX-FileCopyrightText: 2022 Helmholtz-Zentrum Dresden-Rossendorf (HZDR)

SPDX-License-Identifier: GPL-3.0-or-later
-->

# Development Setup

For HELIPORT developement, we suggest creating a dedicated
[new instance config](#creating-a-new-heliport-config)
which can then be used by one developer, or commited to a Git repository and shared.
The development setup should consist of the following files and directories:

```text
.
├── pyproject.toml
├── heliport
│   ├── .git
│   │   └── ...
│   └── ...
└── heliport_config
    ├── __init__.py
    ├── asgi.py
    ├── wsgi.py
    ├── celery.py
    ├── urls.py
    ├── settings.py
    └── .env
```

## Creating a Virtual Environment

Both the dependencies and the config should be installed into a virtual environment.
The example linked above uses Poetry.
For instructions on how to use Poetry, please refer to the
[Poetry documentation](https://python-poetry.org/docs/).

Alternatively, the {ref}`venv module <python:tut-venv>` shipped with Python can be used.
For example:

```shell
python -m venv venv
source venv/bin/activate
python -m pip install -e .
```

Extra packages for development (e.g. `pytest` and `sphinx`) can be installed via
dependency groups within the `heliport` repo:

```shell
python -m pip install --group heliport/pyproject.toml:dev --group heliport/pyproject.toml:docs
```

## Running the Development Server

To start the development server, run:

```shell
heliport-cli migrate
heliport-cli runserver
```

To create an admin user, run:

```bash
heliport-cli createsuperuser
```

This user can be used to access the admin interface at `/admin/`.

## Using the Testing Config

The Pytest command is configured to automatically use the testing config provided in
`testing/config/`.
To execute the tests, run:

```shell
pytest heliport
```

It is also possible to run the development server using the testing config, e.g. when
making small changes.
To do this, certain environment variables have to be set:

```shell
export PYTHONPATH="heliport/testing"
export DJANGO_SETTINGS_MODULE=config.settings

heliport-cli migrate
heliport-cli runserver
```

## Start the Celery Worker

To run background tasks, a Celery worker needs to be running.

Start the Celery worker:

```bash
celery -A heliport_config worker
```

Or run it in the background:

```bash
celery -A heliport_config multi start "celery@$HOSTNAME" --logfile=celery.log --pidfile=celery.pid
```

:::{note}
Make sure you have a Celery Broker installed as described in
[Prerequisites](../administration/prerequisites.rst).
:::

## Build the JavaScript Code Bundles

To build the JavaScript code, the necessary libraries need to be installed.
This can be done by running `yarnpkg install` within the `heliport/` directory.
Then, running `yarnpkg build` will create webpacks of the JavaScript and CSS code.
To start the webpack development server which keeps the webpacks up to date during
development, run `yarnpkg dev`.
If you don't want to change any Javascript code, running the build command once will
suffice.

:::{note}
The `yarnpkg` command refers to the Yarn package manager.
On some systems it might simply be called `yarn`.
:::