177 lines
6.2 KiB
Markdown
177 lines
6.2 KiB
Markdown
# 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)
|