# Integrate a new app

Based on Wekan as a Stackspin app example.

## Flux

### Cluster config

* [ ] Flux kustomization: `flux2/cluster/optional/APP/APP.yaml` (Example: `flux2/cluster/optional/wekan/wekan.yaml`)

### Source (helmRepository / gitRepository)

* [ ] Create new `helmRepository` if needed in `flux2/core/base/sources/APP-helmrepository.yaml` (Example: `flux2/core/base/sources/wekan-helmrepository.yaml`)
* [ ] Include `APP-helmrepository.yaml` in `flux2/core/base/sources/kustomization.yaml`

### App config

* [ ] Add app secrets template: `install/templates/stackspin-APP-variables.yaml.jinja` (Example: `install/templates/stackspin-wekan-variables.yaml.jinja`)
* [ ] If the app is storing state to disk, add PVCs in `flux2/apps/APP/pvc.yaml` (Example: `flux2/apps/wekan/pvc.yaml`)
* [ ] Helm chart values configmap: `flux2/apps/APP/APP-values-configmap.yaml` (Example: `flux2/apps/wekan/wekan-values-configmap.yaml`)
* [ ] `HelmRelease` in `flux2/apps/APP/release.yaml` (Example: `flux2/apps/wekan/release.yaml`)

#### Single sign-on

* Integrate the new app into the single sign-on system
  * [ ] Oauth client resource: `flux2/apps/APP/APP-oauth-client.yaml` (Example: `flux2/apps/wekan/wekan-oauth-client.yaml`)
  * [ ] Configure app OIDC settings, probably via its helm values: `flux2/apps/APP/APP-values-configmap.yaml` (Example: `flux2/apps/wekan/wekan-values-configmap.yaml`)
  * [ ] Disable user/pw login if possible (#881)
  * Test SSO:
    * [ ] Admin login should grant admin privileges
    * [ ] Non-admin login should not grant admin privileges

#### Backup/restore

This applies if the app has any persistent storage that needs to be part of
backups.

* [ ] Add the label `stackspin.net/backupSet=APP` to some kubernetes
  resources. This label is used by Velero when instructed to restore a single
  app. Typically you should add it to:
  * [ ] the pvc(s) in `flux2/apps/APP/pvc*.yaml` (Example: `flux2/apps/wekan/pvc.yaml`)
  * [ ] any pod(s) that use those pvc(s); this would go in the chart's helm
    values configmap, with the value typically called `podLabels`, or if it doesn't have
    that maybe `commonLabels`: `flux2/apps/APP/APP-values-configmap.yaml` (Example: `flux2/apps/wekan/wekan-values-configmap.yaml`)
  * [ ] the kubernetes objects controlling those pods, typically a deployment
    (`deploymentLabels` or `commonLabels`) or statefulset (`statefulSetLabels`
    or `commonLabels`).
* [ ] To the same pods, i.e., the ones that use the pvcs that need to be
  backed up, add an annotation `backup.velero.io/backup-volumes: "volume-name"`,
  where `volume-name` is the name of the volume internal to the pod kubernetes
  object, as shown for example in `kubectl describe pod` output.
* [ ] Add app-specific backup/restore instructions to `docs/maintenance.rst` if
  necessary.

### Etc

* [ ] K8s kustomization: `flux2/apps/APP/kustomization.yaml` (Example: `flux2/apps/wekan/kustomization.yaml`)
      Remember to include all files in the same directory !
* [ ] Add app to `dump_secrets()` in `stackspin/cluster.py`

If you made it until here you have completed all necessary steps for adding a
custom app to your cluster.
If you intend to contribute to Stackspin by a new app merge request please
continue and follow the rest of the steps below.

## Tests

* [ ] Make sure testing app resources work (`test/pytest/test_resources.py`)
* [ ] Make sure testing app cert works (`test/pytest/test_certs.py`)
* [ ] Add app to `dump_secrets()` in `stackspin/cluster.py`
* [ ] Add Taiko test (`tests/taiko`)

## CI

* Add the following elements to `.gitlab-ci.yml`:
  * [ ] `.APP-rules` partial
  * [ ] `enable-APP` job
  * [ ] `APP-kustomization-ready` job
  * [ ] `APP-cert` job
  * [ ] `APP-taiko` test job

## Renovatebot

* [ ] Make sure that latest [renovate pipeline](https://open.greenhost.net/stackspin/renovate/-/pipelines)
      checks for app updates **after the new app is merged into the main branch**

## Documentation

* Add app to:
  * [ ] `Step 3: Install additional applications` in `docs/installation/install_stackspin.rst`
  * [ ] `docs/installation/testing.rst`
  * [ ] `docs/system_administration/migrating.rst`
  * [ ] `docs/usage/applications.rst`

## Follow-up issues

Create follow-up issue with:

* [ ] Limit settings (<https://blog.kubecost.com/blog/requests-and-limits/#our-solution>)
  * [ ] Set CPU request
    * CPU limits are unset.
    * Set CPU request to average CPU usage.
  * [ ] Set memory requests and limits
    * Set memory request to:
      ```
      1.5 * avg(quantile_over_time(.99,container_memory_working_set_bytes{container_name!="POD",container_name!=""}[7d])) by (container_name,pod_name,namespace)`
      ```
    * Limit set to `2 * request`