edp-doc/docs/user-documentation/petclinic.md

# Spring's PetClinic

The [PetClinic](https://github.com/spring-projects/spring-petclinic) has been
Spring's example project for years and is being updated with each new version
of the framework. It consists of a simple, old-school Java webapp and a
PostgreSQL relational database for persistence.

Within the IDP the PetClinic backstage template creates a copy of the PetClinic
code, builds and deploys it. This demonstrates a golden path to set up an
entire development and deployment pipeline of an example or starter
application.

---

## Instance Creation

To instantiate a new PetClinic instance, create a new project from the
PetClinic template in [Backstage](https://cnoe.localtest.me/create). The
template executes the following steps:

1. Download the app source code from the given code repository
2. Apply overrides for compatibility with Forgejo Actions.
3. Create a new git repository in Forgejo and push the merged code.
4. Create a new deployment in ArgoCD.

After the code is pushed into Forgejo the configured workflows in the git
repository are triggered. They compile, test and scan the project and finally
push a container image into Forgejo's internal container registry.

At the same time, ArgoCD starts deploying the newly created instance of the
PetClinic based on the kubernetes manifests located in the git repo. However,
as the application is built from source, the webapp only becomes available as
soon as the container image of the Java app is pushed into the container
registry.

Eventually, the new PetClinic will go live on a subdomain corresponding to the
chosen name in the template, e.g.
[mypetclinic.cnoe.localtest.me](https://mypetclinic.cnoe.localtest.me).

### Build Customizations

The existing GitHub Actions workflows in the upstream PetClinic are overwritten
by the app template as they are not 100% compatible with Forgejo Actions. This
affects predominantly the coordinates of actions as Forgejo can download
actions from other platforms and defaults to actions hosted on
`code.forgejo.org`. Thus, actions from GitHub have to be marked as such
specifically to be found.

Furthermore, the current runner setup does not support nested containerization,
yet. Consequently, all container image builds and interactions avoid the need
for a container engine and opt for alternative tooling such as Google Jib or
evaluating tarballs of image layers.

### Deployment

ArgoCD creates a synchronized deployment from the resources in the git
repository into a dedicated namespace. It contains the deployment of a
PostgreSQL database and the PetClinic Java app, as well as Ingress and
monitoring definitions.

The Prometheus instance included in the IDP stack is instructed to scrape data
from exposed monitoring endpoints on the Java application. The gathered data
can be analyzed in Grafana. Fitting dashboards are currently not part of the
deployment but can be easily imported from Grafana Cloud, board
[4701](https://grafana.com/grafana/dashboards/4701-jvm-micrometer/) is quite
capable of displaying JVM stats provided by Spring Boot's default monitoring.