README.md

-# Example repository for customizing a Stackspin cluster
+# Stackspin Outwards - Stackspout
+
+This repository extends [Stackspin](https://open.greenhost.net/stackspin/stackspin)
+with extra applications and overrides
+focused on business use.
+Once stabilized, the aim is to contribute as much upstream as possible.
+
+Stackspout is used in day-to-day business
+with a double-digit user number,
+so all experiments happen carefully.
+Still, it is an experimental offering.
+
+## Customizations
+
+### Overrides
+- Adds many Nextcloud extensions and some configuration
+  -> most notably `external` to add Applications into Nextcloud as hub
+
+### New Applications
+
+Following are the applications Stackspout adds beyond Stackspin.
+Unlike Stackspin, there is currently no mechanism to add those individually,
+they come in one package with the repository.
+
+Below list is formatted as:
+> subdomain: Service (helmrepo, if not provided by the service authors)
+
+#### Stable including Single-Sign-On
+- forge: Forgejo
+- do: Vikunja
+#### No SSO
+- ninja: InvoiceNinja
+- support: Zammad
+- flow: n8n (8gears)
+- meet: cal.com (pyrrha)
+- status: Gatus (minicloudlabs)
+#### Planned
+- design: penpot (truecharts, waiting on PR)
+- sprint: taiga (nemonik)
+- video: Peertube ([LecygneNoir](https://git.lecygnenoir.info/LecygneNoir/peertube-helm)
+)
+- call: Jitsi Meet / OpenTalk
+- wiki: Wiki (maybe wikijs, but I'd like something that integrated with Nextcloud and Markdown/Orgdown)
+#### Ideas
+- link: URL Shortener
+- connect: Bonfire
+#### Stale
+- people: SuiteCRM (bitnami repo)
+- time: Kimai (robjuz repo)
+
+#### Functionally
+- Nextcloud too slow - add Redis?
+- Preconfigure user settings in Nextcloud, Vikunja and more
+
+## Setup
+
+> Warning: Lots of experiments happening here!
+
+First [install Stackspin](https://docs.stackspin.net/en/latest/installation/install_stackspin.html).
+Then apply the configuration to your cluster:
 
-Example boilerplate for a custom [flux](https://fluxcd.io/) repository
-which can be added to a [Stackspin](https://stackspin.net) cluster.
-The main use-case is to add additional applications
-which are not integrated into Stackspin (yet).
+```sh
+install.sh
+```
 
-For a more advanced example
-see the [flux2-kustomize-helm-example](https://github.com/fluxcd/flux2-kustomize-helm-example)
-repository.
-This repo's directory structure is similar to the `flux2-kustomize-helm-example`
-one.
+Done!
+Note that the added applications are currently only toggled via repository changes
+and integration with Stackspin mechanisms is very rudimentary.
+To list the central resource related to this repo:
 
-## Basic configuration
+```sh
+kubectl get gitrepositories -A
+kubectl get kustomization -A -o=jsonpath='{.items[?(@.spec.sourceRef.name=="stackspout")].metadata.name}'
+kubectl -n stackspout get helmreleases
+kubectl -n stackspout get pods
+```
 
-We'll start with a very basic configuration:
+But there are also ConfigMaps, Secrets, StatefulSets, PVCs, Helmrepos and more...
 
-* It uses a public git repo
-* No secrets are included
-* No forking/modifications needed, install as it is
+### Tools
 
-Apply it to your cluster:
+Useful tools for administration:
+- my `stack` CLI helper, currently part of my dotfiles:
+  https://git.jfischer.org/xeruf/dotfiles/src/branch/main/.config/shell/server#L11
+- stackspin docs:
+  https://docs.stackspin.net/en/v2/system_administration/customizing.html
 
-```sh
-basic/install.sh
-```
+### Guide: Creating OAuth Credentials for an external service
+- push an OAuth2Client definition like for the apps,
+  adjusting `metadata.name` and `spec.secretName` as well as `spec.redirectUris`
+- obtain the generated `client_secret` for your application from kubernetes:
 
-List the resource created by this flux repo:
+      kubectl get secret -n flux-system stackspin-APP-oauth-variables --template '{{.data.client_secret}}' | base64 -d
 
-```sh
-kubectl -n example-basic get gitrepositories
-kubectl -n example-basic get kustomizations
-kubectl -n example-basic get helmreleases
-kubectl -n example-basic get pods
-```
-
-Show output of the single app applied, [podinfo](https://github.com/stefanprodan/podinfo)
+  with client_id:
 
-```sh
-curl --resolve podinfo.local:80:CLUSTER_IPV4_ADDRESS http://podinfo.local
-```
+      kubectl get secret -n flux-system stackspin-APP-oauth-variables --template '{{.data.client_id}}{{"\n"}}{{.data.client_secret}}{{"\n"}}' | while read in; do echo $in | base64 -d; echo; done
 
-## What's next ?
 
-There are two ways of using a custom flux repo to host your custom config/apps
-on a Stackspin cluster.
+## Explanation - Typical App Deployment in Stackspout with Flux on Kubernetes
 
-### A) Manage secrets manually
+The diagram illustrates generically how continuous app deployment works in our Kubernetes cluster
+from Infrastructure-as-Code using flux.
+Not every app has database, backend and frontend,
+but in the end the deployments all work very similarly
+so there is no point showing it for each individual app.
+Except for the Single-Sign On,
+apps also do not really depend on each other.
 
-This approach is easier to start with,
-because you don't need to configure your cluster to handle encrypted secrets
-and access to a private git repository.
+Explanations:
+- deploy :: creates a resource on the cluster from a file in the GitRepository
+- create :: creates a resource on the cluster using Kubernetes logic
+- ... all :: creates multiple independent resources
 
-* Fork this repository into a public git repo, cloneable via `https://`
+All Flux Kustomizations refer to a directory in the GitRepository,
+but for clarity I omitted it beyond the initial one.
 
-### Everything in version control, including secrets
+Clouds are created not via Flux GitOps,
+but through one-time scripts.
 
-* Fork this repository into a private git repo, cloneable via `ssh://`
-* [Configure flux to use ssh instead of https for cloning](https://fluxcd.io/docs/components/source/gitrepositories/#ssh-authentication)
-* You shouln't rely solely on transport encryption for your git repository
-  but rather end-to-end encrypt your secrets.
-  Different methods are available for flux:
-  * [Sops](https://fluxcd.io/docs/guides/mozilla-sops/)
-    [Sops section in flux2-kustomize-helm-example](https://github.com/fluxcd/flux2-kustomize-helm-example#encrypt-kubernetes-secrets)
-  * [Sealed Secrets](https://fluxcd.io/docs/guides/sealed-secrets/)
+![Flux Diagram](./stackspout.png)

adopt-secrets.sh

+#!/bin/bash
+# Copied from Stackspin with slight adjustment to include all new secrets
+set -o errexit
+secrets=$(kubectl get -A 'stringsecrets.v1alpha1.secretgenerator.mittwald.de' | tail +2 | awk '{print $2}' | paste -s -d ' ')
+for secret in $secrets
+do
+  echo "Processing secret $secret"
+  if currentRefs=$(kubectl get secret -n flux-system $secret -o jsonpath={.metadata.ownerReferences})
+  then
+    if [ -n "$currentRefs" ]
+    then
+      echo "There are refs set already, skip."
+      continue
+    fi
+
+    uid=$(kubectl get stringsecret -n flux-system $secret -o jsonpath={.metadata.uid})
+    echo "Patching to add owner reference to StringSecret with uid $uid"
+    kubectl patch secret -n flux-system $secret --patch="{\"metadata\":{\"ownerReferences\":[{\"apiVersion\":\"secretgenerator.mittwald.de/v1alpha1\",\"blockOwnerDeletion\":true,\"controller\":true,\"kind\":\"StringSecret\",\"name\":\"$secret\",\"uid\":\"$uid\"}]}}"
+  else
+    echo "Secret does not exist; perhaps this is a new install or the app is not installed. Skipping."
+  fi
+done
+
+secrets="stackspin-alertmanager-basic-auth stackspin-prometheus-basic-auth"
+for secret in $secrets
+do
+  echo "Processing secret $secret"
+  if currentRefs=$(kubectl get secret -n stackspin $secret -o jsonpath={.metadata.ownerReferences})
+  then
+    if [ -n "$currentRefs" ]
+    then
+      echo "There are refs set already, skip."
+      continue
+    fi
+
+    uid=$(kubectl get basicauth -n stackspin $secret -o jsonpath={.metadata.uid})
+    echo "Patching to add owner reference to BasicAuth with uid $uid"
+    kubectl patch secret -n stackspin $secret --patch="{\"metadata\":{\"ownerReferences\":[{\"apiVersion\":\"secretgenerator.mittwald.de/v1alpha1\",\"blockOwnerDeletion\":true,\"controller\":true,\"kind\":\"BasicAuth\",\"name\":\"$secret\",\"uid\":\"$uid\"}]}}"
+  else
+    echo "Secret does not exist; perhaps this is a new install or the app is not installed. Skipping."
+  fi
+done
+
+echo "Done patching secrets."
+echo "Restarting secrets controller."
+if ! kubectl rollout restart deploy -n secrets-controller secrets-controller-kubernetes-secret-generator
+then
+  echo "Restarting failed. Possibly this is a new install and the secrets controller is not installed yet. Ignoring."
+fi
+echo "adopt-secrets completed"

apps/design-kustomization.yaml

+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+  name: add-design
+  namespace: flux-system
+spec:
+  interval: 10m
+  prune: true
+  path: ./apps/design
+  sourceRef:
+    kind: GitRepository
+    name: stackspout

apps/design/kustomization.yaml

+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - penpot-kustomization.yaml
+  - penpot-secrets-kustomization.yaml

apps/design/penpot-kustomization.yaml

+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+  name: penpot
+  namespace: flux-system
+spec:
+  interval: 5m
+  retryInterval: 2m
+  timeout: 10m
+  wait: true
+  prune: true
+  path: ./apps/design/penpot
+  sourceRef:
+    kind: GitRepository
+    name: stackspout
+  dependsOn:
+    - name: flux
+    - name: local-path-provisioner
+    - name: penpot-secrets
+    - name: nginx
+    - name: single-sign-on
+  postBuild:
+    substituteFrom:
+      - kind: Secret
+        name: stackspin-cluster-variables
+      - kind: ConfigMap
+        name: stackspin-penpot-kustomization-variables
+      - kind: Secret
+        name: stackspin-penpot-variables
+      # OIDC
+      - kind: Secret
+        name: stackspin-penpot-oauth-variables
+      - kind: ConfigMap
+        name: stackspin-single-sign-on-kustomization-variables

apps/design/penpot-secrets-kustomization.yaml

+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+  name: penpot-secrets
+  namespace: flux-system
+spec:
+  interval: 5m
+  timeout: 4m
+  wait: true
+  prune: true
+  path: ./apps/design/penpot-secrets
+  sourceRef:
+    kind: GitRepository
+    name: stackspout
+  dependsOn:
+    - name: flux
+    - name: secrets-controller
+  postBuild:
+    substituteFrom:
+      - kind: Secret
+        name: stackspin-cluster-variables

apps/design/penpot-secrets/penpot-kustomization-variables.yaml

+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: stackspin-penpot-kustomization-variables
+  namespace: flux-system
+data:
+  penpot_domain: design.${domain}

apps/design/penpot-secrets/penpot-oauth-secret.yaml

+---
+apiVersion: secretgenerator.mittwald.de/v1alpha1
+kind: StringSecret
+metadata:
+  name: stackspin-penpot-oauth-variables
+  namespace: flux-system
+spec:
+  data:
+    client_id: penpot
+  fields:
+  - fieldName: client_secret
+    length: "32"

apps/design/penpot-secrets/penpot-variables.yaml

+---
+apiVersion: secretgenerator.mittwald.de/v1alpha1
+kind: StringSecret
+metadata:
+  name: stackspin-penpot-variables
+  namespace: flux-system
+spec:
+  fields:
+  - fieldName: password

apps/design/penpot/penpot-oauth-client.yaml

+apiVersion: hydra.ory.sh/v1alpha1
+kind: OAuth2Client
+metadata:
+  name: penpot-oauth-client
+  # Has to live in the same namespace as the stackspin-penpot-oauth-variables secret
+  namespace: flux-system
+spec:
+  # TODO copied from wekan: https://github.com/wekan/wekan/wiki/Keycloak
+  grantTypes:
+    - authorization_code
+    - refresh_token
+    - client_credentials
+    - implicit
+  responseTypes:
+    - id_token
+    - code
+  scope: "openid profile email stackspin_roles"
+  secretName: stackspin-penpot-oauth-variables
+  #redirectUris:
+  #  - https://${penpot_domain}/oauth/openid/
+  #tokenEndpointAuthMethod: client_secret_post

apps/design/penpot/penpot-pvc.yaml

+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: penpot-data
+  namespace: stackspout
+  labels:
+    stackspin.net/backupSet: "penpot"
+spec:
+  accessModes:
+    - ReadWriteOnce
+  volumeMode: Filesystem
+  resources:
+    requests:
+      storage: 2Gi
+  storageClassName: local-path

apps/design/penpot/penpot-release.yaml

+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+  name: penpot
+  namespace: stackspout
+spec:
+  releaseName: penpot
+  chart:
+    spec:
+      chart: penpot
+      version: 4.0.12
+      sourceRef:
+        kind: HelmRepository
+        name: truecharts
+        namespace: flux-system
+  interval: 5m
+  valuesFrom:
+    - kind: ConfigMap
+      name: stackspin-penpot-values
+      optional: false
+    # Allow overriding values by ConfigMap or Secret
+    - kind: ConfigMap
+      name: stackspin-penpot-override
+      optional: true
+    - kind: Secret
+      name: stackspin-penpot-override
+      optional: true

apps/design/penpot/penpot-values-configmap.yaml

+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: stackspin-penpot-values
+  namespace: stackspout
+data:
+  values.yaml: |
+    # TODO verify structure matches chart
+    commonLabels:
+      stackspin.net/backupSet: "penpot"
+    podLabels:
+      stackspin.net/backupSet: "penpot"
+    # TODO Configure PVC for data & database including backup labels
+    podAnnotations:
+      backup.velero.io/backup-volumes: "data"
+    persistence:
+      enabled: true
+      existingClaim: "penpot-data"
+
+    ingress:
+      main:
+        enabled: true
+        annotations:
+          kubernetes.io/tls-acme: "true"
+        hosts:
+          - host: "${penpot_domain}"
+            paths:
+               - path: /
+                 pathType: Prefix
+        tls:
+          - secretName: penpot-tls
+            hosts:
+              - "${penpot_domain}"
+        integrations:
+          certManager:
+            enabled: true
+    penpot:
+      public_uri: "https://${penpot_domain}"
+      #registration_domain_whitelist: []
+      #flags:
+      #  backend_api_doc: false
+      #  cors: false
+      #  demo_users: false
+      #  demo_warning: false
+      #  insecure_register: false
+      #  log_emails: false
+      #  log_invitation_token: false
+      #  login: true
+      #  mail_verification: true
+      #  registration: true
+      #  secure_session_cookies: true
+      #  user_feedback: false
+      identity_providers:
+        oidc:
+          enabled: true
+          client_id: "${client_id}"
+          client_secret: "${client_secret}"
+          base_uri: "https://${hydra_domain}"
+          #autoDiscoverUrl: 'https://${hydra_domain}/.well-known/openid-configuration'
+      smtp:
+        enabled: "${outgoing_mail_enabled}"
+        host: "${outgoing_mail_smtp_host}"
+        port: "${outgoing_mail_smtp_port}"
+        username: "${outgoing_mail_smtp_user}"
+        pass: "${outgoing_mail_smtp_password}"
+        default_from: "${outgoing_mail_from_address}"
+        default_reply_to: "${outgoing_mail_from_address}"
+
+    persistence:
+      assets:
+        enabled: true
+        mountPath: /opt/data/assets
+        targetSelectAll: true

apps/do-kustomization.yaml

+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+  name: add-do
+  namespace: flux-system
+spec:
+  interval: 10m
+  prune: true
+  path: ./apps/do
+  sourceRef:
+    kind: GitRepository
+    name: stackspout

apps/do/kustomization.yaml

+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - vikunja-secrets-kustomization.yaml
+  - vikunja-kustomization.yaml
+  #- vikunja-test-kustomization.yaml

apps/do/vikunja-kustomization.yaml

+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+  name: vikunja
+  namespace: flux-system
+spec:
+  interval: 5m
+  retryInterval: 2m
+  timeout: 10m
+  wait: true
+  prune: true
+  path: ./apps/do/vikunja
+  sourceRef:
+    kind: GitRepository
+    name: stackspout
+  dependsOn:
+    - name: flux
+    - name: local-path-provisioner
+    - name: vikunja-secrets
+    - name: nginx
+    - name: single-sign-on
+  postBuild:
+    substituteFrom:
+      - kind: Secret
+        name: stackspin-cluster-variables
+      - kind: ConfigMap
+        name: stackspin-vikunja-kustomization-variables
+      - kind: Secret
+        name: stackspin-vikunja-variables
+      # OIDC
+      - kind: Secret
+        name: stackspin-vikunja-oauth-variables
+      - kind: ConfigMap
+        name: stackspin-single-sign-on-kustomization-variables

apps/do/vikunja-secrets-kustomization.yaml

+---
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+  name: vikunja-secrets
+  namespace: flux-system
+spec:
+  interval: 5m
+  timeout: 4m
+  wait: true
+  prune: true
+  path: ./apps/do/vikunja-secrets
+  sourceRef:
+    kind: GitRepository
+    name: stackspout
+  dependsOn:
+    - name: flux
+    - name: secrets-controller
+  postBuild:
+    substituteFrom:
+      - kind: Secret
+        name: stackspin-cluster-variables

apps/do/vikunja-secrets/vikunja-kustomization-variables.yaml

+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: stackspin-vikunja-kustomization-variables
+  namespace: flux-system
+data:
+  vikunja_domain: do.${domain}

apps/do/vikunja-secrets/vikunja-oauth-secret.yaml

+---
+apiVersion: secretgenerator.mittwald.de/v1alpha1
+kind: StringSecret
+metadata:
+  name: stackspin-vikunja-oauth-variables
+  namespace: flux-system
+spec:
+  data:
+    client_id: vikunja
+  fields:
+  - fieldName: client_secret
+    length: "32"

apps/do/vikunja-secrets/vikunja-test-oauth-secret.yaml

+---
+apiVersion: secretgenerator.mittwald.de/v1alpha1
+kind: StringSecret
+metadata:
+  name: stackspin-vikunja-test-oauth-variables
+  namespace: flux-system
+spec:
+  data:
+    client_id: vikunja-test
+  fields:
+  - fieldName: client_secret
+    length: "32"