| //// |
| ****************************************************************************** |
| * Copyright © 2017-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 |
| * |
| ****************************************************************************** |
| //// |
| = [ WIRD AUF KSM ANGEPASST NACH RÜCKSPRACHE IM Kontaktstammdaten: Sprint Review (26.02.2020) ] openKonsequenz - How to deploy the module "eLogbook@openK" |
| Simon Reis <simon.reis@pta.de> |
| :Date: 2020-02-25 |
| :Revision: 2 |
| :icons: |
| :source-highlighter: highlightjs |
| :highlightjs-theme: solarized_dark |
| |
| <<< |
| |
| == Deployment |
| |
| The elogbook application consists of 3 parts regarding the deployment. |
| |
| . Frontend: "elogbookFE"-Directory |
| . Backend: "elogbook.war" |
| . Database: The scripts are found in the "db" folder within the backend sources. |
| |
| === Deployment of the application components |
| |
| ==== Deployment of the frontend |
| |
| The Frontend SPA is built as a folder, that contains all the required files for |
| the application. If you have built the frontend yourself then the content of the "dist"-folder |
| within the Frontend development-directory has to be copied into the target-directory of the apache-tomcat. |
| If you got the Frontend delivered in form of a archive (elogbookFE.zip) put *its content* into the |
| target-directory "elogbookFE" of the apache-tomcat: |
| |
| <Apache-Tomcat>/webapps/elogbookFE |
| |
| If the target folder does not exist, it has to be created manually. |
| |
| ==== Deployment of the backend |
| The backend REST-services are built in form of a "WAR"-file (to be found |
| in the "target"-directory of the MAVEN-directory structure or delivered to you). |
| For deployment, this file has to be copied to the directory |
| |
| <Apache-Tomcat>/webapps |
| |
| ==== Deployment of the database |
| Currently there is no automatic mechanism for distributing structural |
| or content related changes to the database. |
| DB related changes are deployed using database scripts directly in suitable |
| DB management applications like *pgAdminIII* or directly in the *postgres-console*. |
| These script can be found in the backend project in the directory |
| |
| <elogbook backend project directory>/db/postgreSQL |
| |
| |
| . If needed, create the Database and the access role "btbservice" with *"01_add_DB.sql"* |
| . The script *"01a_drop_DB_1.0.0.sql"* is only needed for dropping all objects in the db! |
| . Use the script *"02_create_DB_1.0.0.sql"* to create all database objects |
| . You will probably need to modify the last script *"03_config_DB_1.0.0.sql"* before you run it. Configurate |
| your branches, grid territories and your responsibilities here! |
| |
| TIP: If you want to install the system on an oracle dbms, please take the db scripts from |
| the */db/oracle* subfolder. |
| |
| ==== Configuration of the system |
| |
| ===== DB based configuration |
| |
| . Grid territories - The grid-territories have to be configured in the DB-Table *ref_grid_territory* |
| |
| Please modify the "03_config_DB_*.sql" script (in "<elogbook backend project dir>\db\postgreSQL" ) to change the |
| configuration. (This file is contained in the *oracle* folder as well. |
| |
| ===== Configuration of the webserver |
| |
| There exists the file *context.xml* in the "conf" subdirectory (*<TOMCAT>/conf*) of the target apache tomcat installation. |
| Add the following parameter and resource in order to access the correct backend configuration and to |
| gain access to the database: |
| |
| .context.xml |
| [source,xml] |
| ---- |
| [...] |
| <!-- Uncomment this to disable session persistence across Tomcat restarts --> |
| |
| <!--Manager pathname=""/> |
| |
| <Parameter name="environment" override="false" value="Development"/--> |
| |
| <Parameter name="OK_ELOGBOOK_ENVIRONMENT" override="false" value="Production"/> |
| |
| <Resource name="jdbc/okBetriebstagebuchDS" |
| auth="Container" |
| type="javax.sql.DataSource" |
| driverClassName="org.postgresql.Driver" |
| url="jdbc:postgresql://{dbserver}:5432/{dbname}" |
| username="{dbuser}" |
| password="{dbpassword}"/> |
| |
| |
| <!-- Uncomment this to enable Comet connection tacking (provides events |
| on session expiration as well as webapp lifecycle) --> |
| [...] |
| ---- |
| |
| For oracle please use... |
| |
| .contextOracle.xml |
| [source,xml] |
| ---- |
| [...] |
| <!-- Uncomment this to disable session persistence across Tomcat restarts --> |
| |
| <!--Manager pathname=""/> |
| |
| |
| <Parameter name="environment" override="false" value="Development"/--> |
| |
| <!-- Parameter for different Backend configs --> |
| <Parameter name="OK_ELOGBOOK_ENVIRONMENT" override="false" value="Production"/> |
| |
| <Resource name="jdbc/okBetriebstagebuchDSO" |
| auth="Container" |
| type="javax.sql.DataSource" |
| driverClassName="oracle.jdbc.driver.OracleDriver" |
| url="jdbc:oracle:thin:@{orasvr}:1521:{dbname}" |
| username="{dbuser}" |
| password="{dbpassword}"/> |
| |
| |
| <!-- Uncomment this to enable Comet connection tacking (provides events |
| on session expiration as well as webapp lifecycle) --> |
| [...] |
| ---- |
| |
| *{dbserver}*, *{dbname}*, *{dbuser}* and *{dbpassword}* need to be replaced by the actual values. |
| |
| CAUTION: The postgres database drivers (postgresql-42.0.0.jar or ojdbc7_g.jar} referenced in the *context.xml* needs to be copied from the lib folder within the |
| backend source files to the *<TOMCAT>/lib* folder of the target tomcat installation. |
| |
| (The jar is located in *deploy/lib/*) |
| |
| CAUTION: If you want to use an oracle db then you have to change |
| the file backendConfigProduction: Set "activePersistencyUnit" to "betriebstagebuchORA". |
| (see next chapter "Configuration of the backend"). |
| |
| |
| ===== Configuration of the backend |
| |
| After the backend war file has been deployed and unpacked inside of the *<TOMCAT>/webapps* folder there are different |
| backend config files to be found in the folder *<TOMCAT>/webapps/elogbook/WEB-INF/classes* |
| |
| * backendConfigCustom.json |
| * backendConfigDevLocal.json |
| * backendConfigDevServer.json |
| * backendConfigProduction.json |
| |
| The active configuration is chosen by parameter *OK_ELOGBOOK_ENVIRONMENT* (see context.xml above). |
| Possible values are: |
| |
| * *Custom* (for backendConfigCustom.json) |
| * *DevLocal* (for backendConfigDevLocal.json) |
| * *DevServer* (for backendConfigDevServer.json) |
| * *Production* (for backendConfigProduction.json) |
| |
| After choosing an environment the corresponding json file has to be configured: |
| |
| .backendConfigXXX.json |
| [source,json] |
| ---- |
| { |
| "portalBaseURL" : "http://{hostname}:{port}/portal/rest/beservice", |
| "fileRowToRead": "9", |
| "importFilesFolderPath": "/home/btbservice/importFiles", |
| "activePersistencyUnit": "betriebstagebuch", |
| "applicationAccessRole": "elogbook-access" |
| } |
| ---- |
| * *portalBaseURL* - The portal base url should point the the address where the portal backend (the *Auth&Auth*-Server) |
| can be accessed. This is important for the authorization of the backend services. |
| * *fileRowToRead* - Defines the line number inside the import-file of the relevant text line. |
| * *importFilesFolderPath* - Defines the exchange directory for the import functionality |
| * *activePersistencyUnit* - Defines the active part of the file persistenc.xml. Choose *"betriebstagebuchORA"* for the |
| usage of OracleDB and *"betriebstagebuch"* to use PostgreSQL. |
| * *applicationAccessRole* - Defines the role for which users are fetched (For the selection in shift-change-dialog). |
| |
| |
| == Design Decisions |
| |
| All architecture decisions based on the Architecture Committee Handbook. There are no deviations. |
| |
| == Risks and Technical Debts |
| |
| (Currently there aren't any known issues) |
| |
| <<< |
