docs(petclinic): some adjustments to the petclinic doc

docs/userguide/petclinic.md

@@ -1 +1,65 @@
-patrick
+## 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
+1. Apply overrides for compatibility with Forgejo Actions.
+1. Create a new git repository in Forgejo and push the merged code.
+1. 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.