Merge pull request #239 from com-pas/update-readme

Dennis Labordus · web-flow · commit 8a7340df568b · 2022-07-19T15:43:32.000+02:00
Updated documentation for development
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ SPDX-License-Identifier: Apache-2.0
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5925/badge)](https://bestpractices.coreinfrastructure.org/projects/5925)
 [![Slack](https://raw.githubusercontent.com/com-pas/compas-architecture/master/public/LFEnergy-slack.svg)](http://lfenergy.slack.com/)
 
-# compas-scl-data-service
+# CoMPAS SCL Data Service
 
 Service to store and retrieve the SCL XML to a database.
 
@@ -21,8 +21,9 @@ to [documentation](doc/compas-scl-data-service.md).
 
 There are currently two database implementations available.
 
-- For more information about the BaseX Implementation go to [BaseX](doc/basex.md). (Profile activated by default.)
-- For more information about the PostgreSQL Implementation go to [PostgreSQL](doc/postgresql.md).
+- For more development information about the BaseX Implementation go to [BaseX](doc/basex.md). (Profile activated by
+  default.)
+- For more development information about the PostgreSQL Implementation go to [PostgreSQL](doc/postgresql.md).
 
 > **Note:** When switching between implementation it's a good practise to first execute a maven clean to remove
 > old dependencies from the target directory in the app module.
diff --git a/doc/basex.md b/doc/basex.md
@@ -19,7 +19,31 @@ Below environment variable(s) can be used to configure the connection to BaseX,
 
 ## Development
 
-### Application depends on a running BaseX instance
+### Building the application
+
+You can use Maven to build the application and see if all tests are working using:
+
+```shell script
+./mvnw clean verify
+```
+
+This should normally be enough to also run the application, but there were cases that we need to build using:
+
+```shell script
+./mvnw clean install
+```
+
+This to make the local modules available for the app module to run the application.
+
+### Running the application in dev mode
+
+You can run your application in dev mode that enables live coding using:
+
+```shell script
+./mvnw -DskipTests=true -Dquarkus.profile=dev-basex package io.quarkus:quarkus-maven-plugin::dev
+```
+
+#### Application depends on a running BaseX instance
 
 Check [basexhttp on DockerHub](https://hub.docker.com/r/basex/basexhttp) for a running BaseX docker container. This is
 needed when running the SCL Data Service locally. Not needed to run the tests.
@@ -37,7 +61,7 @@ docker run --rm --name compas_basex \
 > **Note:** Replace <BASEX-DIR> with a directory on your local machine, for instance "~/basex".
 > All data will be stored in this directory under "data". This way data isn't lost after stopping the docker container.
 
-### Application depends on a running KeyCloak instance
+#### Application depends on a running KeyCloak instance
 
 Beside a BaseX Database there is also a KeyCloak instance need to be running on port 8089 by default.
 See [README.md](../README.md#security) for default values, if custom keycloak is used.
@@ -59,34 +83,26 @@ docker run --rm --name compas_keycloak \
    -d compas_keycloak:latest
 ```
 
-### Building the application
+### Creating a Docker image with native executable
 
-You can run the following command to build the BaseX version of the application.
+The releases created in the repository will create a docker image with a native executable. If you're running a Linux
+system it's possible to create and run the executable locally. You can create a Docker image with native executable
+using:
 
 ```shell script
-./mvnw clean verify
+./mvnw package -Pnative-image
 ```
 
-### Running the application in dev mode
-
-You can run your application in dev mode that enables live coding using:
-
-```shell script
-./mvnw -DskipTests=true -Dquarkus.profile=dev-basex package io.quarkus:quarkus-maven-plugin::dev
-```
+You can then execute your native executable with: `./app/target/basex-quarkus-app/app-local-SNAPSHOT-runner`
 
-### Creating a native executable
+### Creating a Docker image with JVM executable
 
-You can create a native executable using:
+There is also a profile to create a Docker Image which runs the application using a JVM. You can create a Docker Image
+with JVM executable using:
 
 ```shell script
-./mvnw -P native package
+./mvnw package -Pjvm-image
 ```
 
-This will run the native executable build in a container. In the native profile the property
-"quarkus.native.container-build" is set to 'true'.
-
-You can then execute your native executable with: `./app/target/basex-quarkus-app/app-local-SNAPSHOT-runner`
-
-If you want to learn more about building native executables, please see https://quarkus.io/guides/maven-tooling.html
-and https://quarkus.io/guides/writing-native-applications-tips.
+The JVM Image can also (temporary) be created by the release action if there are problems creating or running the
+native executable.
diff --git a/doc/compas-scl-data-service.md b/doc/compas-scl-data-service.md
@@ -66,4 +66,10 @@ There a some BaseX specific choices made in storing the SCL.
 
 ### PostgreSQL
 
-TODO
+There a some PostgreSQL choices made in storing the SCL.
+
+- For the PostgreSQL version we use FlyWay to maintain the database schema.
+- All SCL XML Files are stored in a table called `scl_file`.
+- For every new version of an SCL XML File a new record is created.
+- The full XML is stored in a text field `scl_data`.
+- We can use the XPath function of PostgreSQL to retrieve extra info from the XML.
diff --git a/doc/postgresql.md b/doc/postgresql.md
@@ -40,7 +40,31 @@ Table: scl_file
 
 ## Development
 
-### Application depends on a running PostgreSQL instance
+### Building the application
+
+You can use Maven to build the application and see if all tests are working using:
+
+```shell script
+./mvnw clean verify
+```
+
+This should normally be enough to also run the application, but there were cases that we need to build using:
+
+```shell script
+./mvnw clean install
+```
+
+This to make the local modules available for the app module to run the application.
+
+### Running the application in dev mode
+
+You can run your application in dev mode that enables live coding using:
+
+```shell script
+./mvnw -DskipTests=true -Dquarkus.profile=dev-postgresql package io.quarkus:quarkus-maven-plugin::dev
+```
+
+#### Application depends on a running PostgreSQL instance
 
 Check [PostgreSQL on DockerHub](https://hub.docker.com/_/postgres?tab=description) for a running PostgreSQL docker
 container. Use the following command to start the docker container.
@@ -59,7 +83,7 @@ docker run --rm --name compas_postgresql \
 > All data will be stored in this directory under "compas". This way data isn't lost after stopping the docker
 > container.
 
-### Application depends on a running KeyCloak instance
+#### Application depends on a running KeyCloak instance
 
 Beside a PostgreSQL Database there is also a KeyCloak instance need to be running on port 8089 by default.
 See [README.md](../README.md#security) for default values, if custom keycloak is used.
@@ -81,34 +105,26 @@ docker run --rm --name compas_keycloak \
    -d compas_keycloak:latest
 ```
 
-### Building the application
+### Creating a Docker image with native executable
 
-You can run the following command to build the PostgreSQL version of the application.
+The releases created in the repository will create a docker image with a native executable. If you're running a Linux
+system it's possible to create and run the executable locally. You can create a Docker image with native executable
+using:
 
 ```shell script
-./mvnw clean verify
+./mvnw package -Pnative-image
 ```
 
-### Running the application in dev mode
-
-You can run your application in dev mode that enables live coding using:
-
-```shell script
-./mvnw -DskipTests=true -Dquarkus.profile=dev-postgresql package io.quarkus:quarkus-maven-plugin::dev
-```
+You can then execute your native executable with: `./app/target/postgresql-quarkus-app/app-local-SNAPSHOT-runner`
 
-### Creating a native executable
+### Creating a Docker image with JVM executable
 
-You can create a native executable using:
+There is also a profile to create a Docker Image which runs the application using a JVM. You can create a Docker Image
+with JVM executable using:
 
 ```shell script
-./mvnw -P native package
+./mvnw package -Pjvm-image
 ```
 
-This will run the native executable build in a container. In the native profile the property
-"quarkus.native.container-build" is set to 'true'.
-
-You can then execute your native executable with: `./app/target/postgresql-quarkus-app/app-local-SNAPSHOT-runner`
-
-If you want to learn more about building native executables, please see https://quarkus.io/guides/maven-tooling.html
-and https://quarkus.io/guides/writing-native-applications-tips.
+The JVM Image can also (temporary) be created by the release action if there are problems creating or running the
+native executable.
