.. _develop-env:

Development environment
=======================

This document describes the development environment for the vantage6 project. When
developing new features or fixing bugs, it helps a lot to have your code changes
immediately reflected in the running system, which is why we have a development
environment.

The development environment is a `devspace <https://www.devspace.sh/>`_ environment
that runs a local kubernetes environment with all the services that make up a vantage6
infrastructure running in containers.

.. warning::

    If you are using Windows, you need to have the
    `Windows Subsystem for Linux <https://learn.microsoft.com/en-us/windows/wsl/install>`_
    (WSL) installed, and call the development environment from within WSL. The
    development environment is not supported on Windows itself.

Requirements
------------

You need to have the following installed:

- `devspace <https://www.devspace.sh/docs/getting-started/installation>`_ - to run the
  development environment
- `kubectl <https://kubernetes.io/docs/tasks/tools/#kubectl>`_ - to manage the
  kubernetes cluster. It usually comes with your kubernetes distribution. Supported
  distributions for the development environment are `microk8s <https://microk8s.io/>`_,
  `minikube <https://minikube.sigs.k8s.io/>`_ and
  `Docker Desktop <https://docs.docker.com/desktop/>`_.

.. warning::

    If you are using WSL, it may not be possible to open a browser window to
    authenticate from the command line. There are multiple ways to fix this.
    `This StackOverflow question <https://superuser.com/questions/1262977/open-browser-in-host-system-from-windows-subsystem-for-linux>`_
    has some solutions.

Finally, to run the development environment, you need to clone the
`vantage6 repository <https://github.com/vantage6/vantage6>`_ and navigate to the
main directory.

First time running the development environment
----------------------------------

To run the development environment for the first time, execute these commands:

.. code-block:: bash

    cd /path/to/vantage6/repository

    # Recommended but optional: use a specific namespace instead of the default
    # kubernetes namespace.
    kubectl config set-context --current --namespace=vantage6

    # Run the development environment
    devspace run start-dev

The first time you run the development environment, you will be asked to enter a number
of variables to configure the development environment. Take particular note of setting
up the following variables:

- ``HOST_URI``: this is the ip address of your host machine. If you are using Docker
  k8s (which comes with Docker Desktop), this should be ``host.docker.internal``. If
  you are using Linux, this is usually ``172.17.0.1``. You can also find out the ip
  with ``hostname -I | awk '{print $1}'`` (Linux) or
  ``ip route | awk '/default/ {print $3}`` (Mac).
- ``NUMBER_OF_NODES``: this is the number of nodes you want to create for the
  development environment. For some algorithms, you need to have at least 3 nodes.
- ``NODE_TEST_DATABASE_NAME``: this is the name of the test database for the nodes.
  This is used to store the test data for the nodes. Enter a suitable CSV file name.

.. warning::

    If you are using WSL with Docker Desktop, note that you
    `need to set custom mount paths <https://dev.to/nsieg/use-k8s-hostpath-volumes-in-docker-desktop-on-wsl2-4dcl>`_
    for the file paths. Note also that these files may be deleted when you restart
    WSL or your machine itself.

Running the development environment
----------------------------------

Once you have configured the development environment, you can manage it with the
following commands:

.. list-table::
   :name: devspace-commands
   :widths: 33 67
   :header-rows: 1

   * - Command
     - Description
   * - ``v6 dev start``
     - Start the development environment
   * - ``v6 dev stop``
     - Stop the development environment. This removes the running Kubernetes resources
       but keeps the local data (e.g. tasks data, database data)
   * - ``v6 dev clean``
     - Delete all running k8s resources and local data (e.g. tasks data, database data)
   * - ``v6 dev rebuild``
     - Rebuild all infrastructure Docker images (HQ, node, etc.)

By default, ``v6 dev rebuild`` will build all images. You can rebuild specific
images by passing the ``--hq``, ``--node``, ``--store`` or ``--ui`` flag. For
example, if you want to rebuild only the HQ image, you can run:

.. code-block:: bash

    v6 dev rebuild --hq

Using the development environment
--------------------------------

Once the development environment is running, it will spin up the following services:

- The vantage6 hub, consisting of:

  - User interface (http://localhost:7600)
  - HQ (http://localhost:7601/hq)
  - Algorithm store (http://localhost:7602/store)
  - Authentication (Keycloak), including the admin interface (http://localhost:7680)
  - PostgreSQL databases to support the HQ, store and authentication services

- One or more nodes (as indicated by the ``NUMBER_OF_NODES`` variable)

The following user is created to authenticate with:

- Username: ``admin``
- Password: ``admin``

The first time you start the development environment, you will be asked if you want to
populate the hub with some example data. This is useful to test the development
environment. This will create additional users and organizations. The users will have
the username ``user_1`` (for organization ``org_1``), ``user_2`` (for organization
``org_2``), etc., up to the number of nodes you have configured. Each user will have
the password ``Password123!``.

.. note::

    You can find the logs of the development environment in the `.devspace/logs`
    directory. We also recommend using `k9s <https://k9scli.io/>`_ to interact with
    the Kubernetes cluster.