## Spring PetClinic Template

This template can deploy a fork of Spring's PetClinic and showcase the entire
development workflow from version control over build and deployment into
kubernetes to monitoring the state at runtime.

The goal is to demonstrate the migration of an existing GitHub project into the
stack by applying only minimal changes for compatibility. These changes
include:

 - Overwriting the CI workflows due to compatibility with forgejo actions and
    container issues, thus making builds container less.
 - Extending the kubernetes manifests to use Ingress and Service objects
 - Integrate Prometheus monitoring endpoint


### Backstage - Forking

The Backstage template allows you to define a URL to 'fork' from. However,
the template does not actually create a git fork but downloads the latest
`HEAD` from a given branch. The source repository has to be known by backstage
so it can apply the correct download mechanism, see `backend.integrations` in
the backstage config.

In the first step, the original source code is downloaded from the given
upstream repository. Subsequently, overrides provided by the template are
copied into the codebase replacing some workflow and deployment files.

This 'merged' codebase is pushed into a new git repository in the supplied
forgejo instance. Additionally, an ArgoCD deployment is created based on this
new given repo.


### Forgejo - CI with Forgejo Actions

As soon as the patched codebase is pushed into the forgejo git repository,
forgejo actions are triggered and start executing the three existing workflows.
However, only the two build workflows are patched to work within the current
stack, the third deployment workflow fails as it cannot start a kind cluster.

In the current configuration, workflows are by default executed in a minimal
node-debian container. This suffices in most cases to run GitHub actions.

Like in the original upstream repository on GitHub, a Gradle- and a Maven-based
workflow are started. The Gradle one only executes a simple java build while
the Maven version also includes the creation of a container image and a
trivy-based security scan.

Both workflows are patched as referencing of actions differs in forgejo actions
from GitHub actions. In GitHub Actions, actions are rerefenced as paths to
github repositories. In Forgejo Actions, this mechanism similarly refers to
actions hosted on `code.forgejo.org` even on self-hosted instances. As only a
small subset of actions is ported to `code.forgejo.org` due to licensing and
compatibility (not all GitHub actions can work with forgejo actions), forgejo
actions also allow referencing actions by URL. Thus, the action
`https://github.com/actions/setup-java` instructs the forgejo runner to
download the action from GitHub. (The default actions repository can be
overwritten)

Creating the application container within the Maven workflow is accomplished
without using 'native' container tooling, i.e. docker or podman. Besides this
being favorable as it introduces less side effects, the current stack
implementation does not support running nested containers, yet.

Furthermore, as the system uses self-signed certificates, certificate checks
are disabled throughout the system for now.

After a successful build, the container image is published into the Forgejo
container registry and can be pulled for deployment.


### ArgoCD - Deployment

The PetClinic consists of two components, a persistent PostgreSQL database and
the java application that is compiled from source. On execution of the
Backstage template an application deployment is created in ArgoCD. The
resources defined in the newly created git repository are synchronized into the
kubernetes cluster. However, as the java app container has to be built by
the CI workflows, the deployment will initially fail but become successful as
soon as the container image is available.



### Prometheus & Grafana - Monitoring

Prometheus and Grafana among others are deployed as apart of the IDP monitoring
stack. To integrate with these existing components the Backstage template adds
a ServiceMonitor definition to the deployment of the PetClinic. It instructs
Prometheus to scrape the `actuator/prometheus` endpoint in specific intervals.
The data contains jvm health data and can be visualized in Grafana.

As the upstream PetClinic on GitHub does not contain the necessary dependencies
to enable the Prometheus endpoint, the app is by default bootstrapped from
a fork that contains the `micrometer-registry-prometheus` dependency.
