5.4. 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 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 (WSL) installed, and call the development environment from within WSL. The development environment is not supported on Windows itself.

5.4.1. Requirements

You need to have the following installed:

• devspace - to run the development environment

• kubectl - to manage the kubernetes cluster. It usually comes with your kubernetes distribution. Supported distributions for the development environment are microk8s, minikube and Docker 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 has some solutions.

Finally, to run the development environment, you need to clone the vantage6 repository and navigate to the main directory.

5.4.2. First time running the development environment

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

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 for the file paths. Note also that these files may be deleted when you restart WSL or your machine itself.

5.4.3. Running the development environment

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

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:

v6 dev rebuild --hq

5.4.4. 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 to interact with the Kubernetes cluster.