|
| 1 | +<!-- |
| 2 | +SPDX-FileCopyrightText: 2022 Alliander N.V. |
| 3 | +
|
| 4 | +SPDX-License-Identifier: Apache-2.0 |
| 5 | +--> |
| 6 | + |
| 7 | +# Development for CoMPAS SCL Auto Alignment |
| 8 | + |
| 9 | +This project uses Java 17 and Quarkus to build and run the application. The project is split into multi modules. |
| 10 | +The app module will use Quarkus to expose the services as REST XML Endpoints. The service module contains all |
| 11 | +the logic to determine X/Y Coordinates into IEC 61850 XML (using the namespace |
| 12 | +http://www.iec.ch/61850/2003/SCLcoordinates). This module uses no Quarkus dependencies, but mainly standard |
| 13 | +java dependencies and PowSyBl dependencies to determine coordinates. This way the service module can also be used in |
| 14 | +other environment as Java library, for instance a Spring project. |
| 15 | + |
| 16 | +## Building the application |
| 17 | + |
| 18 | +You can use Maven to build the application and see if all tests are working using: |
| 19 | + |
| 20 | +```shell script |
| 21 | +./mvnw clean verify |
| 22 | +``` |
| 23 | + |
| 24 | +This should normally be enough to also run the application, but there were cases that we need to build using: |
| 25 | + |
| 26 | +```shell script |
| 27 | +./mvnw clean install |
| 28 | +``` |
| 29 | + |
| 30 | +This to make the local modules available for the app module to run the application. |
| 31 | + |
| 32 | +## Running the application locally in dev mode |
| 33 | + |
| 34 | +You can run your application in dev mode that enables live coding using: |
| 35 | + |
| 36 | +```shell script |
| 37 | +./mvnw package io.quarkus:quarkus-maven-plugin::dev |
| 38 | +``` |
| 39 | + |
| 40 | +### Application depends on a running KeyCloak instance for dev mode |
| 41 | + |
| 42 | +A KeyCloak instance needs to be running on port 8089 by default in dev mode. If a custom KeyCloak instance is used see |
| 43 | +[Security](README.md#security) for more details. |
| 44 | + |
| 45 | +There is a preconfigured Demo KeyCloak instance available for CoMPAS in the |
| 46 | +[CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment). This repository can be cloned and |
| 47 | +used to execute the following commands to create a local Docker Image with the CoMPAS Demo configuration. |
| 48 | + |
| 49 | +```shell |
| 50 | +cd <CoMPAS Deployment Repository Directory>/compas/keycloak |
| 51 | +docker build -t compas_keycloak . |
| 52 | +``` |
| 53 | + |
| 54 | +A Docker Image `compas_keycloak` is created that can be started using the following command |
| 55 | + |
| 56 | +```shell |
| 57 | +docker run --rm --name compas_keycloak \ |
| 58 | + -p 8089:8080 |
| 59 | + -d compas_keycloak:latest |
| 60 | +``` |
| 61 | + |
| 62 | +There are now 3 users available to be used, `scl-data-editor`, `scl-data-reader`, `scd-reader`. See |
| 63 | +[CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment) for more information about the users. |
| 64 | + |
| 65 | +## Testing the application |
| 66 | + |
| 67 | +The application is tested with unit and integration tests, but you can also manually test the application using for |
| 68 | +instance Postman. And there is also a way to test this service with the CoMPAS OpenSCD Frontend application. |
| 69 | + |
| 70 | +### Postman |
| 71 | + |
| 72 | +To manually test the application there is a Postman collection in the directory `postman` that can be imported |
| 73 | +and used to execute REST XML Calls. |
| 74 | + |
| 75 | +To make the call work we also need to import an environment and authorisation collection. These files can be found |
| 76 | +in [CoMPAS Deployment Repository](https://github.com/com-pas/compas-deployment) in the directory `postman` |
| 77 | +(`auth.collection.json` and `local.environment.json`). |
| 78 | + |
| 79 | +In the authorisation collection there are called for the 3 users known within the Demo KeyCloak instance. |
| 80 | +If one of these calls are executed there is a variable `bearer` filled. |
| 81 | + |
| 82 | +Now one of the SCL Auto Alignment calls can be executed, the variable `bearer` is added to the header of the request. |
| 83 | +After the call is executed the result should be shown in Postman. |
| 84 | + |
| 85 | +### CoMPAS OpenSCD Frontend application |
| 86 | + |
| 87 | +To test the SCL Auto Alignment with the CoMPAS OpenSCD application just run the application in dev mode, including the |
| 88 | +KeyCloak instance. For further instruction how to start the CoMPAS OpenSCD application and use this locally see |
| 89 | +the file `DEVELOPMENT.md` in [CoMPAS OpenSCD application](https://github.com/com-pas/compas-open-scd). |
| 90 | + |
| 91 | +## Docker Images |
| 92 | + |
| 93 | +### Creating a Docker image with native executable |
| 94 | + |
| 95 | +The releases created in the repository will create a docker image with a native executable. If you're running a Linux |
| 96 | +system it's possible to create and run the executable locally. You can create a Docker image with native executable |
| 97 | +using: |
| 98 | + |
| 99 | +```shell script |
| 100 | +./mvnw package -Pnative-image |
| 101 | +``` |
| 102 | + |
| 103 | +You can then execute your native executable with: `./app/target/app-local-SNAPSHOT-runner` |
| 104 | + |
| 105 | +### Creating a Docker image with JVM executable |
| 106 | + |
| 107 | +There is also a profile to create a Docker Image which runs the application using a JVM. You can create a Docker Image |
| 108 | +with JVM executable using: |
| 109 | + |
| 110 | +```shell script |
| 111 | +./mvnw package -Pjvm-image |
| 112 | +``` |
| 113 | + |
| 114 | +The JVM Image can also (temporary) be created by the release action if there are problems creating or running the |
| 115 | +native executable. |
0 commit comments