# 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 script needs you to have access to the Kubernetes cluster that runs
Stackspin. Point the `KUBECONFIG` environment variable to a kubectl config.
Attention points:
- The kubeconfig will be mounted inside docker containers, so also make sure
your Docker user can read it.
- The bind-mount done by docker might not work if the file pointed to is
part of a filesystem such as sshfs. In that case, copy the file to a local
drive first.
## 5. Build and run
To recap, you now have:
- A running Stackspin _provisioning machine_ (the [Stackspin repository](https://open.greenhost.net/stackspin/stackspin) is installed and running on your computer)
- A running Stackspin cluster (a VPS that you successfully connected to from your computer)
- Implemented 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, as the script also builds and installs all the necessary stuff in the dashboard's docker container. But running `yarn install` locally will let your IDE enable all of its bells and whistles, as it will be expecting to find all the necessary in the `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, make sure to increase the chart version number in `Chart.yaml`, and
push your work to a MR. 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.