dashboard/README.md

# Stackspin dashboard backend

Backend for the [Stackspin dashboard](https://open.greenhost.net/stackspin/dashboard)

## Login application

Apart from the dashboard backend this repository 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

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 end-points for the Dashboard,
as well as Kratos and Hydra, will point to `localhost` in that cluster.
As a result, you can run those components locally, and still log into Stackspin
applications that run on the cluster.


## Setting up the local development environment

After this process is finished, the following will run locally:

- The [dashboard](https://open.greenhost.net/stackspin/dashboard)
- The
  [dashboard-backend](https://open.greenhost.net/stackspin/dashboard-backend)

The following will be available on localhost through a proxy and port-forwards:

- Hydra
- Kratos
- The MariaDB database connections

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


### 1. Setup port forwards

To be able to work on the dashboard,
we have to configure our development system to access all the remote services and endpoints.

A helper script is available in this directory
to setup and redirect the relevant ports locally.
It will open ports 8000, 8080, 4445, 3306 to get access to all APIs.
To use it, you'll need `kubectl` access to the cluster:

1. Install `kubectl` (available through `snap` on Linux)
2. Download the kubeconfig: `scp root@stackspin.example.com:/etc/rancher/k3s/k3s.yaml kube_config_stackspin.example.com.yaml`
3. Set `kubectl` to use the kubeconfig: `export KUBECONFIG=$PWD/kube_config_stackspin.example.com.yaml`.
4. Test if it works:

   ```
   kubectl get ingress -n stackspin
   ```

   Should return something like:

   ```
   NAME                                 CLASS    HOSTS                             ADDRESS         PORTS     AGE
   hydra-public                         <none>   sso.stackspin.example.com            213.108.110.5   80, 443   39d
   dashboard                            <none>   dashboard.stackspin.example.com      213.108.110.5   80, 443   150d
   kube-prometheus-stack-grafana        <none>   grafana.stackspin.example.com        213.108.110.5   80, 443   108d
   kube-prometheus-stack-alertmanager   <none>   alertmanager.stackspin.example.com   213.108.110.5   80, 443   108d
   kube-prometheus-stack-prometheus     <none>   prometheus.stackspin.example.com     213.108.110.5   80, 443   108d
   ```
5. Run the script to forward ports of the services to your local setup:

   ```
   ./set-port-forward.sh
   ```

   As long as the script runs, your connection stays open.
   End the script by pressing `ctrl + c` and your port-forwards will end as well.

### 2. Configure a local proxy

Because of strict CORS headers,
we have to map the public Kratos API and login app,
which we will run locally with a local proxy.

This can be done with any proxy server, here we use `nginx`.
Be sure you have NGINX installed and listening on port 80 locally:
`sudo apt-get install nginx` should be enough.

Now configure NGINX with this configuration in `/etc/nginx/sites-enabled/default`

```
server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /var/www/html;

    index index.html;

    server_name _;

    # Flask app and dashboard-backend
    location / {
        proxy_pass http://127.0.0.1:5000/;
        proxy_redirect     default;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    }

    # Kratos APIs
    location /kratos/  {
        proxy_pass http://127.0.0.1:8080/;
        proxy_redirect     default;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    }
}
```

Reload your NGINX:

```
sudo systemctl reload nginx.service
```

### 3. Run FLASK app

Now it is time to start the flask app.
Please make sure you are using Python 3 in your environment.
And install the required dependencies:

```
pip3 install -r requirements.txt
```

Then copy `run_app.sh` to `run_app.local.sh` and change the secrets defined in it.

You can now start the app by running

```
./run_app.local.sh
```

Lastly, start the [dashboard front-end app](https://open.greenhost.net/stackspin/dashboard/#yarn-start)