README.md

# 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](https://open.greenhost.net/stackspin/dashboard-dev-overrides#dashboard-dev-overrides)
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](https://open.greenhost.net/stackspin/dashboard-dev-overrides) repository, editing your `/etc/hosts` file, etc)
- A copy of the [Stackspin Dashboard repository](https://open.greenhost.net/stackspin/dashboard) 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 run`yarn 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.