| //// |
| ****************************************************************************** |
| * Copyright © 2018 PTA GmbH. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| ****************************************************************************** |
| //// |
| = openKonsequenz - How to run the module "Plannedgridmeasures" |
| :Date: 2018-06-25 |
| :Revision: 1 |
| :icons: |
| :source-highlighter: highlightjs |
| :highlightjs-theme: solarized_dark |
| |
| <<< |
| |
| IMPORTANT: Please be sure that you have first *Portal (Auth n Auth)* installed and configured! |
| |
| == Requirements |
| * Java 8 Runtime Environment |
| * Build-Artifacts (look at *howtoBuild* or you get them from a Jenkins source as zip): |
| ** MicsHomeService Backend |
| ** MicsCentralService Backend-Microservice |
| ** PlannedGridMeasures Backend-Microservice |
| ** PlannedGridMeasures Frontend |
| |
| == Prerequisites |
| |
| * *To see this application running you have to run Portal application too.* The reason is the authentication, which happened in the Portal login phase. |
| |
| ==== Install and Configure Apache Tomcat |
| Tomcat is an open-source Java Servlet Container and provides a "pure Java" HTTP web server environment in which Java code can run. |
| |
| 1. Download Tomcat version 8.5.24 from https://archive.apache.org/dist/tomcat/tomcat-8/v8.5.24/bin |
| and extract it (apache-tomcat-8.5.24.zip). |
| 2. Configure Tomcat: |
| a. Configure the *context.xml* file. Copy the *<Resource … >* block from the project file `deploy/conf/`*context.xml* |
| and paste it in the `<tomcat>/conf/`*context.xml* in the *<Context>* block. |
| |
| b. Dont forget to save it. |
| |
| |
| TIP: For more informations check *Deployment View* Chapter in *http://87.128.212.254:8880/gridMeasuresADoc/architectureDocumentation.html[PlannedGridMeasures Architecture Documentation]*. |
| |
| ** Tomcat also needs the database driver to be placed in `<tomcat>/lib`. Find it in the project file `deploy/lib/`*postgresql-xxx.jar*. |
| |
| TIP: It's recommend to install a service for starting and stopping the Apache Tomcat. |
| |
| ==== Install and Configure a PostgreSQL database |
| |
| * A developing and administrating software for databases |
| |
| ** To work with a postgreSQL database is pgAdmin suggested |
| |
| 1. Download and install pgAdmin (version 3 is used during developing process) from: |
| https://www.pgadmin.org/download/ |
| 2. Create a database and adapt the `<tomcat>/conf/`*context.xml* file to your database (look at *Install and Configure Apache Tomcat*). |
| |
| 3. To initialize the database schema run the last sql script: |
| |
| /db/migrations/V0_XX__CREATE_PLGM_DB.sql |
| |
| TIP: It's recommend to install a service for starting and stopping the PostgreSQL database. |
| |
| TIP: For detailed instructions look at *http://87.128.212.254:8880/gridMeasuresADoc/architectureDocumentation.html[PlannedGridMeasures Architecture Documentation]*. |
| |
| == How to deploy and run the Backend |
| To run the backend you need to have installed and configured Apache Tomcat (look at *Install and Configure Apache Tomcat*). |
| The Backend exists of 3 Artifacts: |
| |
| ** One Web Application Archive (war) file which is deployed on a Apache Tomcat |
| *** MicsHomeService (*mics-home-service.war*) |
| ** Two Java Archives (jar) started as Microservices |
| *** MicsCentralService Backend-Microservice (*mics-central-service.jar*) |
| *** PlannedGridMeasures Backend-Microservice (*planned-grid-measures.jar*) |
| |
| |
| === Deploy MicsHomeService (war-file) and start Apache Tomcat |
| Tomcat needs the Web Application Archive (war) file. Either you got it through a successfully maven build or via zip from a Jenkins source. |
| |
| 1. Copy the *mics-home-service.war* file from the `/target` folder of project "MicsHomeService" (zip or maven-build) in the `<tomcat>/webapps` file. If there is a folder named *mics-home-service*, delete it before. |
| 2. Navigate to your `apache-tomcat-8.5.24\bin` folder and start Tomcat by clicking on *startup.bat* (Windows) or executing *startup.sh* (Linux). |
| * Tomcat's default port is *8080*. |
| |
| [source,text] |
| ---- |
| If 8080 port is already in use, you have to change tomcat's port as follows: |
| - Go to <tomcat>/conf folder |
| - Open server.xml file and search for "Connector port" |
| - Replace "8080" by your port number (for example 8181) |
| - Restart tomcat server (in the same folder which startup.bat is located, you can also find a shutdown.bat file). |
| ---- |
| IMPORTANT: If you change the port number you have also adapt the port in the |
| frontend project: File "<PRJ_plannedGridMeasuresFE>/proxy.conf.json" |
| |
| [start=3] |
| 3. Stop your the Apache Tomcat. |
| 4. Navigate to `webapps/mics-home-service/WEB-INF/classes` and open *backendConfigProduction.json* |
| |
| ---- |
| { |
| "micsDistributionCluster" : "openK", |
| "micsCentralURL" : "http://169.50.13.154:9010/mics/central", |
| "micsHealthStateExtraPath" : "healthcheck?pretty=true", |
| "micsCentralIsHttps" : false |
| } |
| ---- |
| [start=5] |
| 5. Set the "micsCentralURL" accordingly. Change the IP to the server where the MicsCentralService Microservice is/will be installed on. |
| 6. Start your Apache Tomcat. |
| |
| |
| === Deploy and start Microservices |
| |
| ==== Microservices File Structures |
| Doesn't matter if you got the artifacts as a zip file from a Jenkins source or as a maven built result (look at *howtoBuild*), |
| the final structure and existence of the files/folders has to look like the following layout (see File/Folder Structure below) after you deployed it to your choosen |
| folder. |
| |
| a. If you got it as zip it should already has the correct structure after extraction. (ignore b.) |
| b. If you have a maven built: |
| * The needed jar-file is always in the `/target` folder of the related project folder after a successfully maven build (look at *howtoBuild*). |
| The other needed files and folders are in the root folder `/` of the related project after a successfully maven build. |
| |
| ==== MicsCentralService Backend-Microservice |
| |
| ===== File/Folder Structure |
| ---- |
| <yourChoosenFolder_MicsCentralService>/mics-central-service.jar |
| /serviceConfig_QA.yml |
| /servicesDistributionQAServer.json |
| ---- |
| ===== Configuring and starting the microservice |
| The name of `*.yml` file can be changed but you have to use the same file as starting parameter when starting |
| the microservice later on. In our example it's `serviceConfig_QA.yml`. |
| |
| *serviceConfig_QA.yml* |
| ---- |
| servicesDistributionFileName: servicesDistributionQAServer.json |
| |
| |
| logging: |
| level: INFO |
| appenders: |
| - type: file |
| currentLogFilename: /opt/mics/logs/mics-central-service.log |
| threshold: ALL |
| archive: true |
| archivedLogFilenamePattern: /opt/mics/logs/mics-central-service-%d.log |
| archivedFileCount: 5 |
| timeZone: UTC |
| loggers: |
| org.eclipse.openk: DEBUG |
| org.eclipse.jetty.servlets: DEBUG |
| |
| server: |
| applicationConnectors: |
| - type: http |
| port: 9010 |
| adminConnectors: |
| - type: http |
| port: 9011 |
| |
| |
| ---- |
| |
| ** servicesDistributionFileName: The file name of the configuration for the intercommunictaion between the services (see below). |
| ** applicationConnectors: Type and port on which the microservice is running. |
| The latest set of socalled "service distribution cluster" can be found in the Architecture documentation. |
| |
| |
| *servicesDistributionQAServer.json* |
| ---- |
| { |
| "active": "true", |
| "clustername": "openK", |
| "description": "service cluster for openKonsequenz", |
| "distributions": [ |
| { |
| "active": "true", |
| "name": "planned-grid-measures.openK", |
| "protocol": "http", |
| "host": "169.50.13.154", |
| "urlPath": "/mics/gridmeasures", |
| "portApp": "9050", |
| "portHealth": "9051", |
| "description": "Planned Grid Measures Backend" |
| }, |
| { |
| "active": "true", |
| "name": "authNauth.openK", |
| "protocol": "http", |
| "host": "169.50.13.154", |
| "urlPath": "/portal/rest/beservice", |
| "healthUrlPath": "/portal/rest/beservice", |
| "portApp": "8080", |
| "portHealth": "8080", |
| "description": "Auth&Auth-Modul" |
| }, |
| { |
| "active": "true", |
| "name": "mics-central-service", |
| "protocol": "http", |
| "host": "169.50.13.154", |
| "urlPath": "/mics/central", |
| "portApp": "9010", |
| "portHealth": "9011", |
| "description": "Mics Central Service-Configures and dispatches different service clusters for different modules" |
| } |
| ] |
| } |
| ---- |
| |
| |
| ** "name" : Name of the service (must not be changed, since it hardwired in the client-applications!) |
| ** "protocol" : HTTP or HTTPS |
| ** "host" : IP of the server where the service can be reached |
| ** "urlPath" : (must not be changed) |
| ** "portApp" : Port of the service. For example for `mics-central-service` its `9010` because thats what we |
| configured in the related `serviceConfig_QA.yml` under `applicationConnectors` -> `type` and `port`. |
| ** "portHealth": Port of the dropWizard-Health-Service. |
| ** "description" : Description of the service |
| |
| The microservice can now be started via Java-Runtime in a console from your <yourChoosenFolder_MicsCentralService>: |
| |
| Remeber to use the *.yml file whaterver you renamed it to as parameter like below, in our example it's `serviceConfig_QA.yml`: |
| ---- |
| java -jar mics-central-service.jar server serviceConfig_QA.yml |
| ---- |
| |
| TIP: It's recommend to install this java microservice execution as a service. |
| |
| ==== PlannedGridMeasures Backend-Microservice |
| |
| ===== File/Folder Structure |
| ---- |
| <yourChoosenFolder_PlannedGridMeasures>/planned-grid-measures.jar |
| /qserver.yml |
| /roleAccessConfiguration/role-access-definition.json |
| /emailConfiguration/mailTemplatesPaths.json |
| /emailConfiguration/emailTemplates/<MULTIPLE_EMAIL_TEMPLATES>.txt |
| ---- |
| ===== Configuring and starting the microservice |
| The name of `*.yml` file can be changed but you have to use the same file as starting parameter when starting |
| the microservice later on. In our example it's `qserver.yml`. |
| |
| *qserver.yml* |
| ---- |
| persistencyUnit: planned-grid-measures-devserver |
| portalBaseURL: http://localhost:8080/portal/rest/beservice |
| whiteListDocumenttypes: application/pdf,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.ms-excel.sheet.macroEnabled.12,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.ms-word.document.macroEnabled.12,image/png,image/jpeg |
| |
| |
| dbConn: |
| driver: org.postgresql.Driver |
| url: jdbc:postgresql://localhost:5432/plannedgridmeasuresqa |
| user: plgm_service |
| password: plgm_service |
| |
| emailConfiguration: |
| smtpHost: localhost |
| port: 1025 |
| sender: testSenderDevServer@test.de |
| |
| logging: |
| level: INFO |
| appenders: |
| - type: file |
| currentLogFilename: /opt/mics/logs/planned-grid-measures.log |
| threshold: ALL |
| archive: true |
| archivedLogFilenamePattern: /opt/mics/logs/planned-grid-measures-%d.log |
| archivedFileCount: 5 |
| timeZone: UTC |
| loggers: |
| org.eclipse.openk: DEBUG |
| org.eclipse.jetty.servlets: DEBUG |
| |
| server: |
| applicationConnectors: |
| - type: http |
| port: 9050 |
| adminConnectors: |
| - type: http |
| port: 9051 |
| |
| ---- |
| ** portalBaseURL: The URL to the Auth&Auth Module (Backend) |
| ** whiteListDocumenttypes: File types you want to allow for upload in *MIME-Type* |
| (https://wiki.selfhtml.org/wiki/MIME-Type/%C3%9Cbersicht) |
| ** dbConn: Configuration of your postgreSQL database |
| ** applicationConnectors: Type and port on which the microservice is running |
| |
| |
| The microservice can now be started via Java-Runtime in a console from your <yourChoosenFolder_PlannedGridMeasures>. |
| Remeber to use the *.yml file whaterver you renamed it to as parameter like below, in our example it's `qserver.yml`: |
| |
| ---- |
| java -jar planned-grid-measures.jar server qserver.yml |
| ---- |
| |
| TIP: It's recommend to install this java microservice execution as a service. |
| |
| TIP: Look at the *http://87.128.212.254:8880/gridMeasuresADoc/architectureDocumentation.html[PlannedGridMeasures Architecture Documentation]* for informations about the services. |
| |
| == How to deploy and run the Frontend |
| Go to `<tomcat>/webapps` folder, if there is a folder named *plannedGridMeasures*, delete it before. |
| If you got it from a Jenkins source as zip extract the content to the `<tomcat>/webapps` folder. |
| If you have a maven-build, copy the content of the `dist` folder in the project folder of "PlannedGridMeasures Frontend" to `<tomcat>/webapps/plannedGridMeasures`. |
| |
| Nevertheless guarantee the following file/folder structure after extraction/copying: |
| ---- |
| <tomcat>/webapps/plannedGridMeasures |
| <tomcat>/webapps/plannedGridMeasures/index.html |
| <tomcat>/webapps/plannedGridMeasures/*.* |
| <tomcat>/webapps/plannedGridMeasures/assets/*.* |
| ---- |
| |
| |
| |
