Stackspin Dashboard

This repo hosts the Stackspin Dashboard, both frontend and backend code.

Project structure

Frontend

The frontend code lives in the frontend directory.

Backend

The backend code lives in the backend directory. Apart from the dashboard backend itself, it also contains a flask application that functions as the identity provider, login, consent and logout endpoints for the OpenID Connect (OIDC) process.

The application relies on the following components:

• Hydra: Hydra is an open source OIDC server. It means applications can connect to Hydra to start a session with a user. Hydra provides the application with the username and other roles/claims for the application. Hydra is developed by Ory and has security as one of their top priorities.

• Kratos: This is Identity Manager and contains all the user profiles and secrets (passwords). Kratos is designed to work mostly between UI (browser) and kratos directly, over a public API endpoint. Authentication, form-validation, etc. are all handled by Kratos. Kratos only provides an API and not UI itself. Kratos provides an admin API as well, which is only used from the server-side flask app to create/delete users.

• MariaDB: The login application, as well as Hydra and Kratos, need to store data. This is done in a MariaDB database server. There is one instance with three databases. As all databases are very small we do not foresee resource limitation problems.

If Hydra hits a new session/user, it has to know if this user has access. To do so, the user has to login through a login application. This application is developed by the Stackspin team (Greenhost) and is part of this repository. It is a Python Flask application The application follows flows defined in Kratos, and as such a lot of the interaction is done in the web-browser, rather then server-side. As a result, the login application has a UI component which relies heavily on JavaScript. As this is a relatively small application, it is based on traditional Bootstrap + JQuery.

Development environment

After this process is finished, the following will run in local docker containers:

• the dashboard frontend
• the dashboard backend

The following will be available through proxies running in local docker containers and port-forwards:

• Hydra admin API
• Kratos admin API and public API
• The MariaDB database

These need to be available locally, because Kratos wants to run on the same domain as the front-end that serves the login interface.

Setup

Before you start, make sure your machine has the required software installed, as per official documentation: https://docs.stackspin.net/en/v2/installation/install_cli.html#preparing-the-provisioning-machine.

Please read through all subsections to set up your environment before attempting to run the dashboard locally.

1. Stackspin cluster

To develop the Dashboard, you need a Stackspin cluster that is set up as a development environment. Follow the instructions in the dashboard-dev-overrides repository in order to set up a development-capable cluster. The Dashboard, as well as Kratos and Hydra, will be configured to point their endpoints to http://stackspin_proxy:8081 in that cluster. As a result, you can run components using the docker-compose.yml file in this repository, and still log into Stackspin applications that run on the cluster.

2. Environment for frontend

The frontend needs to know where the backend API and hydra can be reached. To configure it, create a local.env file in the frontend directory:

cp local.env.example local.env

3. Setup hosts file

The application will run on http://stackspin_proxy. Add the following line to /etc/hosts to be able to access that from your browser:

127.0.0.1	stackspin_proxy

4. Kubernetes access

The ./run_app.sh script needs to access the Kubernetes cluster that runs your Stackspin instance. If you followed the setup as above, you will have a YAML configuration file somewhere on your machine -- usually in the clusters directory of your Stackspin local repository -- called kube_config_cluster.yml. This file holds all the configuration information (URLs, domain names, certificate data) needed to connect to the instance.

Copy that file into the backend/kubeconfig directory.

If you wish to connect this dashboard to another Stackspin cluster, you can replace the kube_config_cluster.yml file with the one that's in that Stackspin's clusters directory.

5. Build and run

To recap, you now have:

• All the software and configurations as described above
• A running Stackspin cluster (a VPS somewhere in The Cloud)
• A kube_config_cluster.yml file in the backend/kubeconfig that will tell the script how to connect to your Stackspin cluster of choice
• Overrides for local dashboard development (by installing and running the Dashboard Dev Overrides repository, editing your /etc/hosts file, etc)
• A copy of the Stackspin Dashboard repository on your device.

That's a lot of work! Good job.

Setup your local dev environment

Before you actually run the main script, cd into the /frontend directory and runyarn install.

This is not strictly necessary for development; the script already builds and installs all the necessary modules in the dashboard's docker container. But running yarn install locally will let your IDE enable all of its bells and whistles like linting, autocorrecting, intellisense etc. Without this step, your IDE will most probably complain it cannot find any modules to import, as there is no node_modules folder.

Let's Run this App

After you've finished all setup steps, you can run everything using:

./run_app.sh

This script

• sets a few environment variables based on the content in your cluster secrets, and
• runs docker compose up to build and run all necessary components, including a reverse proxy and the backend flask application.

If you're curious about what docker compose up does, you can check out the docker-compose.yml file. If you are curious about what docker compose up means, you can start here: https://github.com/docker/compose or even here: https://en.wikipedia.org/wiki/Infrastructure_as_code.

This should be it, congratulations!! If you're having issues, or if something is not working properly, please open an issue or get in touch: info@stackspin.net

Testing as a part of Stackspin

Sometimes you may want to make more fundamental changes to the dashboard that might behave differently in the local development environment compared to a regular Stackspin instance, i.e., one that's not a local/cluster hybrid. In this case, you'll want to run your new version in a regular Stackspin cluster.

To do that:

• Push your work to an MR.
• Set the image tags in values.yaml to the one created for your branch; if unsure, check the available tags in the Gitlab container registry for the dashboard project.
• Make sure to increase the chart version number in Chart.yaml, preferably with a suffix to denote that it's not a stable version. For example, if the last stable release is 1.2.3, make the version 1.2.4-myawesomefeature in your branch.

The CI pipeline should then publish your new chart version in the Gitlab helm chart repo for the dashboard project, but in the unstable channel -- the stable channel is reserved for chart versions that have been merged to the main branch.

Once your package is published, use it by

1. changing the spec.url field of the flux-system/dashboard HelmRepository object in the cluster where you want to run this, replacing stable by unstable; and
2. changing the spec.chart.spec.version field of the stackspin/dashboard HelmRelease to your chart version (the one from this chart's Chart.yaml).

Release process

To publish a new version of the helm chart:

1. Increase the docker image tag in deployment/helmchart/values.yaml so it uses the new tag (to be created in a later step of this release).
2. Update the appVersion in deployment/helmchart/Chart.yaml to match that new tag version.
3. Increase the chart version in deployment/helmchart/Chart.yaml.
4. Update CHANGELOG.md and/or deployment/helmchart/CHANGELOG.md and check that it includes relevant changes, including ones added by renovatebot.
5. Commit and push these changes to main.
6. Create a new git tag for the new release and push it to gitlab as well.

The last step will trigger a CI run that will package and publish the helm chart.