DHX-adapter

DHX adapterserveri paigaldusjuhend

Sisukord

1. Sissejuhatus

DHX adapterserver on tarkvara, mis hõlbustab DHX dokumendivahetuse protokolli kasutuselevõtmist.

DHX adapterserveri toimimise loogika on kirjeldatud DHX adapterserveri kasutusjuhendis.

DHX adapterserveri haldamine on kirjeldatud DHX adapterserveri haldusjuhendis.

Minimaalne (kõik komponendid ühes serveris) paigalduse vaade on järgmine

DHX adapterserver nõuab XTEE turvaserverit (XTEE turvaserveri paremeetrite seadistamine: vt. “4.2.5. Muuta dhx-application.properties”)

2. Tarkvara nõuded (baastarkvara eeldused)

Märkus (muud andmebaasid):

Tõenäoliselt toimib tarkvara ka muude Hibernate ORM poolt toetatud SQL andmebaasi serveritel, nagu MySQL ja Microsoft SQL Server, samuti PostgreSQL ja Oracle vanemate ja uuemate versioonidega.

NB! DHX adapterserveri töötamine on testitud ainult PostgreSQL 9.6 ja Oracle 11g andmebaasi serveri versioonidega.

Seega muude andmebaasi serverite ja versioonide kasutamine toimub omal riisikol ja ei pruugi töötada.

Paigalduspaketina alla laetav WAR fail sisaldab ainult PostgreSQL ja Oracle andmebaasiga suhtlemise JDBC draivereid. Kui soovitakse kasutada muud andmebaasi, siis tuleb dhx-adapter-serveri WAR fail ise uuesti ehitada, muutes pom.xml failis sõltuvusi.

Märkus (muud Java web serverid):

Apache Tomcat tarkvara võib asendada mõne muu Java Web konteiner tarkvaraga. Näiteks GlassFish, WildFly (JBoss) või Jetty.

Paigalduspaketina alla laetav WAR fail sisaldab ainult Apache Tomcat serverisse paigaldamise spring-boot-starter mooduleid. Kui soovitakse kasutatakse muud Java serverit, siis tuleb dhx-adapter-serveri WAR fail ise uuesti ehitada, muutes pom.xml failis sõltuvusi.

3. Riistvara nõuded (eeldused)

Minimaalsed nõuded riistvarale on järgmised:

Optimaalsed riistvara nõuded sõltuvad asutuse poolt saadetavate dokumentide arvust ja suurusest. Samuti sellest kas andmebaasi server paigaldatakse samasse masinasse või eraldi. Soovitav on minimaalsed nõuded kahega korrutada.

4. Paigaldamine

4.1. Olemasoleva paigalduspaketiga (WAR) - Tomcat ja PostgeSQL

4.1.1. PostgreSQL 9.6

Laadida alla ja installeerida PostgreSQL andmebaasi versioon 9.6.x.

Luuua uus andmebaasi kasutaja (Role). Vaata PostgreSQL juhend

CREATE USER dhxuser WITH PASSWORD '123';

Luua uus andmebaas (näiteks nimega dhx_adapter). Vaata PostgreSQL juhend.

CREATE DATABASE dhx_adapter;

Anda loodud kasutajale kõik selle andmebaasi õigused.

GRANT ALL PRIVILEGES ON DATABASE dhx_adapter to dhxuser;

4.1.2. Java SE

4.1.2.1. Java 8 SE

Laadida alla ja installeerida Java 8 SE Runtime environment.

4.1.2.2. Java 11+ SE

!!!TÄHELEPANU!!! Alates Oracle JDK 11-st on oluliselt muutunud Java litsents, mis lubab seda kasutada tasuta vaid personaalseks ja arenduse otstarbeks. Komplikatsioonide tekkimise vältimiseks kasutada OpenJDK väljalaskeid

Laadida alla ja paigaldada OpenJDK.

4.1.3. Apache Tomcat 7

1) Laadida alla ja installeerida (pakkida lahti) Apache Tomcat 7 või uuem versioon.

2) Tekitada kataloogi apache-tomcat-7.x.x/bin uus fail nimega setenv.bat (Windows) või setenv.sh (Linux/Unix).

Lisada sellesse faili allolevad read.

Windows:

set JRE_HOME="C:\Program Files\Java\jre1.8.0_112"
set CATALINA_OPTS=-Xms2048m -Xmx2048m -Djava.awt.headless=true -server
exit /b 0

Linux/Unix:

JRE_HOME=/usr/java/latest
CATALINA_OPTS="-Xms2048m -Xmx2048m -Djava.awt.headless=true -server"
CATALINA_PID="$CATALINA_BASE/tomcat.pid"

Märkus (JRE_HOME):

Näites toodud JRE_HOME kataloogitee (C:\Program Files\Java\jre1.8.0_112 või /usr/java/latest) asendada vastavalt enda installatsioonile.

Märkus (Java mälu suurus):

CATALINA_OPTS parameetris määratakse Tomcat Java protsessi poolt kasutatava mälu suurus.

Kui kasutatakse minimaalset riistvaralist häälestust (masinas muutmälu 2Gb), siis võiks see olla 1Gb ehk -Xms1024m -Xmx1024m

Kui kasutatakse optimaalsemat riistvaralist häälestust (masinas muutmälu 4Gb-8Gb), siis võiks see olla 2Gb kuni 4Gb ehk -Xms2048m -Xmx2048m või -Xms4096m -Xmx4096m

3) Soovi korral muuta ümber Tomcat TCP/IP pordi number (vaikimisi 8080) failis apache-tomcat-7.x.x/conf/server.xml.

    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />

4) Käivitada Tomcat skriptiga apache-tomcat-7.x.x/bin/startup.bat (windows) või apache-tomcat-7.x.x/bin/startup.sh (Linux/Unix).

4.1.4. DHX adapterserver WAR

1) Laadida alla DHX adapterserveri viimase versiooni WAR fail dhx-adapter-server.war. https://github.com/e-gov/DHX-adapter/releases/

2) Kopeerida see Tomcat apache-tomcat-7.x.x/webapps alamkataloogi (Näiteks Windows keskkonnas C:\Program Files\apache-tomcat-7.0.73\webapps\ alamkataloogi).

3) Tomcat püüab seejärel automaatselt WAR faili avada ja paigaldada (deploy).

4) Tekib uus alamkataloog webapps/dhx-adapter-server. Aga kuna WAR fail sisaldab valesid andmebaasi ühenduse parameetreid, siis Tomcat konsoolile/logisse kuvatakse viga.

4.1.5. Muuta dhx-application.properties

1) Avada fail webapps/dhx-adapter-server/WEB-INF/classes/dhx-application.properties ja muuta seal õigeks andmebaasi ühenduse, X-tee turvaserveri ja asutuse registrikoodi parameetrid

soap.security-server=http://TURVASERVERI_AADRESS
soap.xroad-instance=ee-dev
soap.member-class=GOV
soap.member-code=40000001

documents.folder=C:\\dhx_docs\\

spring.datasource.url=jdbc:postgresql://localhost:5432/dhx_adapter
spring.datasource.username=dhxuser
spring.datasource.password=123456
spring.datasource.driver-class-name=org.postgresql.Driver
spring.jpa.properties.hibernate.dialect = org.hibernate.dialect.PostgreSQL94Dialect

Kui turvaserveri poole pöördumisel kasutatakse HTTPS protokolli, siis seadistada järgnevad parameetrid (http puhul jätta muutmata)

soap.client-truststore-file=${JAVA_HOME}/jre/lib/security/cacerts
soap.client-truststore-password=changeit
soap.client-truststore-type=JKS
soap.client-keystore-file=dhx.jks
soap.client-keystore-password=changeit
soap.client-keystore-type=JKS

Teha muudetud dhx-application.properties failist backup koopia kuhugi mujale kataloogi.

Võtmehoidla puudumisel tuleb luua võtmehoidla järgnevalt (nimi, parool ja kestvus valida sobiv)

keytool -genkey -keyalg RSA -alias dhx -keypass changeit -keystore dhx.jks -storepass changeit -validity 360

Seejärel tuleb eksportida sertifikaat, mis tuleb paigutada tuvaserverisse

keytool -export -keystore dhx.jks -alias dhx -file dhx_key.cer

Juhul kui turvaserveri sertifikaat on self-signed, tuleb see lisada java truststore-i.

keytool -import -alias ca -file cert.cer -keystore cacerts -storepass changeit

2) Luua ülaltoodud kataloog C:\dhx_docs\ (Windows) või /dhs_docs (Linux/Unix) ja kontrollida kas Tomcat protsessi käivitaval kasutajal on seal kirjutamise õigused.

3) Avada fail apache-tomcat-7.x.x/webapps/dhx-adapter-server/WEB-INF/classes/log4j2.xml ja muuta log4j2.xml sees soovi korral ümber logimise kataloog (c://logs/dhx-adapter-server.log):

    <RollingFile name="RollingFile" fileName="c://logs/dhx-adapter-server.log"
                 filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log">

Seal võib ka muuta log taseme väiksemaks (info või error). Vaata Log4j juhend

<Logger name="ee.ria" level="debug" additivity="false">

4) Teha Tomcati restart.

Stop apache-tomcat-7.x.x/bin/shutdown.bat (windows) või apache-tomcat-7.x.x/bin/shutdown.sh (Linux/Unix).

Start apache-tomcat-7.x.x/bin/startup.bat (windows) või apache-tomcat-7.x.x/bin/startup.sh (Linux/Unix).

Märkus:

Andmebaasi ühenduse esmakordsel avamisel kontrollitakse kas vajalikud andmebaasi tabelid on juba olemas. Kui tabeleid ei ole, siis luuakse need automaatselt (eraldi SQL skriptiga ei ole vaja andmebaasi tabeleid luua)

Selle määrab dhx-application.properties failis parameeter spring.jpa.hibernate.ddl-auto=update . Vaata Spring boot juhendist.

5) Vaadata, kas Tomcat konsoolis või logis esineb veel vigu (ei tohiks esineda)

4.1.6. Paigaldada Tomcat Windows Servicena või Linux deemonina.

Selleks saab kasutada skripti apache-tomcat-7.x.x/bin/service.bat (Windows) või apache-tomcat-7.x.x/bin/daemon.sh (Linux/Unix).

Näiteks käivitades käsurealt: service.bat install

Vaata täpsemalt Tomcat Windows service HOW-TO.

4.2. Tomcat ja Oracle 11g Express edition

4.2.1. Oracle 11g Express Edition

1) NB! Alates 1.0.5 versioonist tuleb Oracle andmebaasi kasutamiseks paigalduspakk ise ehitada

2) Laadida alla ja installeerida Oracle 11g XE.

3) Logida oracle andmebaasi SYS kasutaja ja luua uus kasutaja (schema):

create user dhxadapter
  identified by dhxadapter123
  DEFAULT TABLESPACE USERS;

grant connect to dhxadapter;
grant resource to dhxadapter;
grant unlimited tablespace to dhxadapter;

4.2.2. Java SE

4.2.2.1. Java 8 SE

Vaata eespoolt

4.2.2.2. Java 11+ SE

Vaata eespoolt

4.2.3. Apache Tomcat 7

Vaata eespoolt

4.2.4. DHX adapterserver WAR

Vaata eespoolt

4.2.5. Muuta dhx-application.properties

Kõige olulisemad on XTEE turvaserveri parameetrid. Nende abil DHX adapterserver küsib käivitamisel XTEE-lt konfiguratsiooni ning edaspidi suhtleb XTEE kaudu teiste asutustega.

1) Avada fail webapps/dhx-adapter-server/WEB-INF/classes/dhx-application.properties ja muuta seal õigeks andmebaasi ühenduse, X-tee turvaserveri ja asutuse registrikoodi parameetrid

soap.security-server=http://TURVASERVERI_AADRESS
soap.xroad-instance=ee-dev
soap.member-class=GOV
soap.member-code=40000001

documents.folder=C:\\dhx_docs\\

spring.datasource.url=jdbc:oracle:thin:dhxadapter/dhxadapter123@localhost:1521:xe
spring.jpa.database-platform=org.hibernate.dialect.Oracle10gDialect
spring.datasource.driver-class-name=oracle.jdbc.OracleDriver
spring.datasource.type=oracle.jdbc.pool.OracleDataSource

Kui turvaserveri poole pöördumisel kasutatakse HTTPS protokolli, siis seadistada järgnevad parameetrid (http puhul jätta muutmata)

soap.client-truststore-file=${JAVA_HOME}/jre/lib/security/cacerts
soap.client-truststore-password=changeit
soap.client-truststore-type=JKS
soap.client-keystore-file=dhx.jks
soap.client-keystore-password=changeit
soap.client-keystore-type=JKS

Teha muudetud dhx-application.properties failist backup koopia kuhugi mujale kataloogi.

Võtmehoidla puudumisel tuleb luua võtmehoidla järgnevalt (nimi, parool ja kestvus valida sobiv)

keytool -genkey -keyalg RSA -alias dhx -keypass changeit -keystore dhx.jks -storepass changeit -validity 360

Seejärel tuleb eksportida sertifikaat, mis tuleb paigutada tuvaserverisse

keytool -export -keystore dhx.jks -alias dhx -file dhx_key.cer

Juhul kui turvaserveri sertifikaat on self-signed, tuleb see lisada java truststore-i.

keytool -import -alias ca -file cert.cer -keystore cacerts -storepass changeit

2) Luua ülaltoodud kataloog C:\dhx_docs\ (Windows) või /dhs_docs (Linux/Unix) ja kontrollida kas Tomcat protsessi käivitaval kasutajal on seal kirjutamise õigused.

3) Avada fail apache-tomcat-7.x.x/webapps/dhx-adapter-server/WEB-INF/classes/log4j2.xml ja muuta log4j2.xml sees soovi korral ümber logimise kataloog (c://logs/dhx-adapter-server.log):

    <RollingFile name="RollingFile" fileName="c://logs/dhx-adapter-server.log"
                 filePattern="logs/$${date:yyyy-MM}/app-%d{MM-dd-yyyy}-%i.log">

Seal võib ka muuta log taseme väiksemaks (info või error). Vaata Log4j juhend

<Logger name="ee.ria" level="debug" additivity="false">

4) Teha Tomcati restart.

Stop apache-tomcat-7.x.x/bin/shutdown.bat (windows) või apache-tomcat-7.x.x/bin/shutdown.sh (Linux/Unix).

Start apache-tomcat-7.x.x/bin/startup.bat (windows) või apache-tomcat-7.x.x/bin/startup.sh (Linux/Unix).

5) Vaadata kas Tomcat konsoolis või logis esineb veel vigu (ei tohiks esineda)

4.2.6. Paigaldada Tomcat Windows Servicena või Linux deemonina.

Vaata eespoolt

4.3. Paigalduspaketi ise ehitamine

Kui soovitakse tarkvara paigalda mingisse muuse Java Web serverisse (mitte Tomcat) või kasutada muud andmebaasi serverit (mitte PostgreSQL), siis tuleb WAR fail ise uuesti ehitada, muutes eelnevalt /DHX-adapter/dhx-adapter-server/pom.xml failis sõltuvusi.

Kui soovitakse paigaldada Java Servlet spetsifikatsiooni 3.0 või uuemat versiooni toetavasse Java Web Konteinerisse, mis toetavad annotatsioone, siis piisab Spring-boot-starter’ite häälestamisest pom.xml sees (vaikimisi on seal spring-boot-starter-web, spring-boot-starter-tomcat, spring-boot-starter-data-jpa).

Vaata Spring juhendist.

Kui soovitakse paigaldada vanemasse Java Web Konteinerisse, siis tuleb häälestus teha Web.xml kaudu. Selle kohta vaata täpsemalt DHX Java teegi kasutusjuhend.

4.3.1. Installeerida Apache Maven ehitustarkvara

1) Laadida alla ja installeerida Java Development Kit (JDK) 7 või 8 või uuem.

Märkus:

Ainult Java Runtime Environment (JRE) ei ole piisav Maveni kasutamiseks.

Pärast installeerimist veenduda, et keskkonna muutuja JAVA_HOME viitab õigesse JDK kataloogi (näiteks C:\Program Files\Java\jdk1.8.0_121).

Käsurealt saab seda kontrollida käsuga echo %JAVA_HOME% (Windows) või echo $JAVA_HOME (Linux/Unix).

Kui ei viita, siis paranda JAVA_HOME.

2) Laadida alla Apache Maven.

3) Pakkida see lahti, näiteks kataloogi C:\Program Files, nii et tekib kataloog C:\Program Files\apache-maven-3.3.9\

4) Lisada tekkinud kataloogi “bin” alamakataloog (näiteks C:\Program Files\apache-maven-3.3.9\bin) PATH keskkonna muutujasse. Alternatiiv on kasutada “mvn.cmd” (Windows) või “mvn” (Linux shell) skripte täispika kataloogi teega.

4.3.2. Laadida alla Oracle JDBC draiver (ojdbc6.jar)

Laadida alla Oracle JDBC draiver ojdbc6.jar (nõuab registreerimist ja sisselogimist).

Märkus:

Oracle ei ole soovinud ise oma JDBC draiverite JAR faile Central Maven reposse üles laadida, seepärast peab selle käsitsi alla laadima ja Maven lokaalsesse REPOsse paigaldama.

Alternatiiviks on laadida ojdbc6.jar vanem versioon alla siit.

Alternatiiviks (kui ei kasututa Oracle andmebaasi) on /DHX-adapter/dhx-adapter-server/pom.xml seest eemaldada read:

		<dependency>
			<groupId>com.oracle</groupId>
			<artifactId>ojdbc6</artifactId>
			<version>11.2.0.4</version>
		</dependency>

4.3.3. Paigaldada ojdbc6.jar lokaalsesse Maven reposse

Selleks minna kataloogi kuhu ojdbc6.jar alla laeti, näiteks:

cd C:\Users\kasutaja\Downloads

Käivitada seal Maven käsk:

mvn install:install-file -Dfile=ojdbc6.jar -DgroupId=com.oracle -DartifactId=ojdbc6 -Dversion=11.2.0.4 -Dpackaging=jar

4.3.4. Laadida alla DHX-adapter lähtekood

Laadida alla (“download” või “git clone”) DHX-adapter lähtekood.

4.3.5. Kompileerida lähtekood Maven-iga

1) Käsurealt minna lähtekoodi kataloogi. Näiteks:

cd C:\Users\kasutaja\git\DHX-adapter

2) Käivitada Maven ehitamine

mvn clean install -Denv=production

Märkus:

Võtmega -Denv=production määratakse ära millisest kataloogist võetakse WAR sisse lisatavad häälestus failid (dhx-application.properties ja log4j2.xml).

Väärtus -Denv=production määrab, et kataloogi DHX-adapter/src/main/resources/conf/production/server alamkataloogist.

Väärtus -Denv=development määrab, et kataloogi DHX-adapter/src/main/resources/conf/development/server alamkataloogist.

JDK11 puhul käivitada ehitamine käsuga mvn clean install -q -P jdk11,production

Selle väljundiks peaks olema SUCCESS:

[INFO] Reactor Summary:
[INFO]
[INFO] DHX-adapter ....................................... SUCCESS [2.903s]
[INFO] dhx-adapter-core .................................. SUCCESS [10.183s]
[INFO] Web services ...................................... SUCCESS [35.038s]
[INFO] dhx-adapter-server ................................ SUCCESS [1:13.734s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Kompileeritud JAR failid tekivad Maven lokaalsesse reposse kataloogi C:\Users\kasutaja\.m2\repository\ee\ria\dhx (Windows) või /home/kasutaja/.m2/repository/ee/ria/dhx (Linux/Unix).

4.3.6. Paigaldada WAR fail

1) Võtta Maven lokaalsest repost ( kasutaja/.m2/repository/ee/ria/dhx/dhx-adapter-server/1.0.1) tekkinud fail dhx-adapter-server-1.0.1.war ja nimetada see ümber dhx-adapter-server.war.

2) Teostada WAR paigaldamine Web Konteiner (Tomcat) serverisse. Vaata eespool.

5. DHX teenuste registreerimine ja avamine X-tee turvaserveris

Järgnevalt eeldatakse, et asutus on X-tee liikmeks registreerunud, paigaldanud X-tee turvaserveri ja registreerinud enda DHX* alamsüsteemi(d) RIHAs. Selle kohta vaata täpsemalt X-tee rakendusjuhendist.

1) Lisada turvaserveris uus klient enda asutuse DHX alamsüsteemile ja registreerida see (Turvaserveris menüü Configuration->Security Server Clients->Add Client).

Vaata X-tee turvaserveri kasutusjuhendist (PDF) punkt “4.2. ADDING A SECURITY SERVER CLIENT”.

2) Lisada DHX adapterserveri välise DHX liidese WSDL ja teenuse URL uue turvaserveri kliendi juurde.

Vaata X-tee turvaserveri kasutusjuhendist (PDF) punktid “6.1. ADDING A WSDL” ja “6.6. CHANGING THE PARAMETERS OF A SERVICE”.

Välise DHX liidese WSDL asub DHX adapterserveris üldjuhul aadressil http://<HOST>:<PORT>/dhx-adapter-server/ws/dhx.wsdl.

Välise DHX liidese teenuse URL (Service URL) asub DHX adapterserveris üldjuhul aadressil http://<HOST>:<PORT>/dhx-adapter-server/ws.

2.1) Turvaserveris valida menüü Configuration->Security Server Clients ja eelnevalt lisatud kliendi juures klikata “Services”.

2.2) Seejärel valida “Add WSDL” ja sisestada välise DHX liidese WSDL aadress (http://<HOST>:<PORT>/dhx-adapter-server/ws/dhx.wsdl, asendades <HOST> ja <PORT> enda DHX adapterserveri väärtustega).

2.3) Seejärel valida tekkinud teenuse “sendDocument” peal “Edit” ja sisestada “Service URL” väärtuseks välise DHX liidese teenuse URL (http://<HOST>:<PORT>/dhx-adapter-server/ws, asendades <HOST> ja <PORT> enda DHX adapterserveri väärtustega)

3) Määrata juurdepääsuõiguseid uuele teenusele.

Vaata X-tee turvaserveri kasutusjuhendist (PDF) punkt “7.1. CHANGING THE ACCESS RIGHTS OF A SERVICE”.

3.1) Turvaserveris valida menüü Configuration->Security Server Clients ja eelnevalt lisatud kliendi juures avada teenused “Services”.

3.2) Teenuse “sendDocument” peal valida “Access Rights” ja seejärel “Add Subjects”-

3.3) Lisada õigus globaalsele X-tee grupile “Kõik X-tee kasutajad”

Märkus:

Üldjuhul piisab õiguste andmisest ainult “sendDocument” teenusele, ning “representationList” teenust võib ignoreerida.

“representationList” teenusele õiguste andmine on vajalik ainult siis, kui asutus käitub DHX vahendajana.

6. Häälestus fail (dhx-application.properties)

Põhilised häälestus failis esinevad parameetrid on toodud DHX Java teegi kasutusjuhendis.

Lisaks neile tuleb täiendavalt lisada parameetrid

Parameeter Vaikimisi väärtus Näite väärtus Kirjeldus
dhx.server.send-to-dhx   */20 * * * * ? Mitme sekundi järel käivitub Sisemise liidese kaudu vastu võetud dokumentide DHX-i edasi saatmise taustatöö. Crontab formaat kujul: <second> <minute> <hour> <day> <month> <weekday>. Väärtus */20 tähendab igal 20-nendal ühikul. Seega */20 * * * * ? tähendab iga 20 sekundi järel.
dhx.server.special-organisations   adit,kovtp,rt,eelnoud DVK alamsüsteemide erandid, millele korral võib DHX adapterserveri sisemist (DVK) teenust kasutada ainult nime järgi (ei ole vaja organistatsiooni koodi)
dhx.server.delete-old-documents   delete-all delete-all määrab, et nii dokumendi metaandmed kui ka sisu (fail) kustutatakse perioodilise puhastus protsessi poolt. delete-content määrab, et ainult fail kustutatakse (baasi jäävad metaandmete kirjed alles). Muu väärtus jätab kõik alles.
dhx.server.delete-old-documents-freq   */20 * * * * ? Vanade dokumentide kustutamise taustatöö käivitamise periood. Kustutatakse ainult dokumendid, mis on vanemad kui alljärgnevate parameetritega määratud päevade arv (30 päeva). Crontab formaat kujul: <second> <minute> <hour> <day> <month> <weekday>. Väärtus */20 tähendab igal 20-nendal ühikul. Seega */20 * * * * ? tähendab iga 20 sekundi järel.
dhx.server.received-document-lifetime   30 Määrab päevade arvu, kui kauaks jäetakse õnnelikult vastu võetud ja edastatud dokument andmebaasi alles. Kustutamine sõltub ka parameetri dhx.server.delete-old-documents väärtusest.
dhx.server.failed-document-lifetime   30 Määrab päevade arvu, kui kauaks jäetakse probleemselt (veaga) edastatud dokument andmebaasi alles. Kustutamine sõltub ka parameetri dhx.server.delete-old-documents väärtusest.
dhx.resend.timeout   1500 Ajaperiood (minutites, 1500 min=25 tundi), pärast mida proovitakse uuesti “saatmisel” staatusesse jäänud dokumente saata. Peaks olema suurem kui document-resend-template parameetris määratud aegade summa. Kasutatakse reaalselt saatmisel ainult erijuhul kui server kukkus maha või serveri töö peatati sunnitult.
dhx.server-include-xmlns-to-attachments false false Määrab, et SOAP vastuse manuste sees ei tooda ära nimeruumi (vastus näiteks <keha><dhl_id>59</dhl_id></keha>). Kui määrata true, siis vastuse manuses tuuakse ära ka nimeruum, näiteks: <keha xmlns="http://producers.dhl.xrd.riik.ee/producer/dhl" ><dhl_id>59</dhl_id></keha>
documents.folder   C:\\dhx_docs\\ Kataloog kuhu salvestatakse vastu võetud (edastamist ootavate) dokumentide kapslid. Linux korral kasutada formaati /kataloog. Selle kataloogi failisüsteemis peab olema piisavalt vaba ruumi (10-50Gb). Dokumendid kustutatakse teatud perioodi (30 päeva) järel (parameetrid dhx.server.received-document-lifetime ja dhx.server.failed-document-lifetime)
soap.dhx.attachment.cache.threshold 0 10 Määrab faili suuruse megabaitides millest alates DHX puhverdab saatmisel ja vastuvõtmisel päringu kettale. Vaikimisi DHX ei puhverda sõnumeid kettale.
soap.dhx.attachment.cache.dir java.io.tmpdir /tmp Kataloog kuhu DHX puhverdab faili saatmisel ja vastuvõtmisel sõnumid. Vaikimisi Java TMP kaust.

PostgreSQL korral tuleb muuta järgmiste parameetrite väärtused.

Parameeter Vaikimisi väärtus Näite väärtus Kirjeldus
spring.datasource.url   jdbc:postgresql://localhost:5432/dhx_adapter Postgres andmebaasi host (localhost), port (5432) ja andmebaasi nimi (dhx_adapter)
spring.datasource.username   dhxuser Postgres andmebaasi kasutajanimi
spring.datasource.password   123 Posgres andmebaasi kasutaja parool
spring.datasource.driver-class-name   org.postgresql.Driver Määrab, et kasutame Postgres JDBC draiverit
spring.jpa.properties.hibernate.dialect   org.hibernate.dialect.PostgreSQL94Dialect Kasutada väärtust “PostgreSQL94Dialect” nii PosgreSQL 9.4 kui ka 9.5 ja 9.6 versioonide korral (väärtusi PostgreSQL95Dialect ja PostgreSQL96Dialect ei eksisteeri).

Oracle 11G kasutamise korral tuleb muuta järgmiste parameetrite väärtused.

Parameeter Vaikimisi väärtus Näite väärtus Kirjeldus
spring.datasource.url   jdbc:oracle:thin:dhxadapter/dhxadapter123@localhost:1521:xe Oracle andmebaasi host (localhost), port (1521), SID (xe), kasutajanimi (dhxadapter) ja parool (dhxadapter123).
spring.jpa.database-platform   org.hibernate.dialect.Oracle10gDialect Määrab, et kasutame Oracle andmebaasi.
spring.datasource.driver-class-name   oracle.jdbc.OracleDriver Määrab, et kasutame Oracle JDBC draiverit.
spring.datasource.type   oracle.jdbc.pool.OracleDataSource Määrab, et kasutame Oracle data source

Märkus:

Enamikel juhtudel piisab kui muuta ainult järgmiste parameetrite väärtused

 soap.security-server=http://TURVASERVERI_AADRESS
 soap.xroad-instance=ee
 soap.member-class=GOV
 soap.member-code=40000001
 documents.folder = C:\\dhx_docs\\
 spring.datasource.url=jdbc:postgresql://localhost:5432/dhx_adapter
 spring.datasource.username=dhxuser
 spring.datasource.password=1*2*3
 spring.datasource.driver-class-name=org.postgresql.Driver
 spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQL94Dialect

Kui turvaserveri poole pöördumisel kasutatakse HTTPS protokolli, siis seadistada järgnevad parameetrid (http puhul jätta muutmata).

soap.client-truststore-file=${JAVA_HOME}/jre/lib/security/cacerts
soap.client-truststore-password=changeit
soap.client-truststore-type=JKS
soap.client-keystore-file=dhx.jks
soap.client-keystore-password=changeit
soap.client-keystore-type=JKS

Ülejäänud parameetrid võib jätta samaks, nagu vaikimisi määratud.

Võtmehoidla puudumisel tuleb luua võtmehoidla järgnevalt (nimi, parool ja kestvus valida sobiv)

keytool -genkey -keyalg RSA -alias dhx -keypass changeit -keystore dhx.jks -storepass changeit -validity 360

Seejärel tuleb eksportida sertifikaat, mis tuleb paigutada tuvaserverisse

keytool -export -keystore dhx.jks -alias dhx -file dhx_key.cer

Juhul kui turvaserveri sertifikaat on self-signed, tuleb see lisada java truststore-i.

keytool -import -alias ca -file cert.cer -keystore cacerts -storepass changeit

/health ja /metrics rakendusinfole juurdepääsusks tuleb nende liideste turvapiirangud kas väljalülitada:

management.security.enabled=false

või konfigureerida vastavalt (kasutusesoleva) Spring Boot -i juhendile.

7. Klastrisse paigaldamine (Failover/Load balancing)

DHX adapterserveri võib paigaldada failover või load balancing klastrisse.

Sellisel paigaldamisel tuleb arvestada, et ühised (jagatud) ressursid on

Näiteks üks võimalik paigalduse variant oleks järgmine

Legend:

Klastrisse paigaldamisel tuleb arvestada et:

Klastrisse paigaldusel võib kasutada ka sellist varianti kus sõlmega A suhtleb ainult X-tee turvaserver, sõlmega B suhtleb ainult asutuse DHS süsteem:

8. Teadaolevad probleemid (sõltuvuste konfliktid)

Kui DHX adapterserver soovitakse paigalda samasse Java/Tomcat serverisse, kus töötab mõni muu Java serveri tarkvara moodul (WAR), siis peab arvestama, et võivad esineda sõltuvuste konfliktid.

Vaata DHX Java teegi kasutusjuhend.

9. Paigalduse testimine (SoapUI)

Paigaldust saab soovi korral testida SoapUI programmiga.

Kui järgnev SOAP päring “getSendingOptions” annab positiivse vastuse, siis võib olla kindel, et toimivad:

1) Avada SoapUI ja lisada uus projekt, sisestades WSDL aadressiks http://localhost:8080/dhx-adapter-server/wsServer/dhlv1.wsdl (muuta vajadusel host ja port).

2) Genereeritud projekti all avada dhlSoapBinding->getSendingOptions->Request 1.

3) Üleval ripploendis kuvatakse teenuse aadress. Valida seal “Edit current” ja sisestada aadressiks http://localhost:8080/dhx-adapter-server/wsServer (muuta vajadusel host ja port).

4) Sisestada Request XML väljale järgmine väärtus, muutes endale sobivaks väärtused ee-dev, GOV ja 40000001 (asutuse enda registrikood)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xro="http://x-road.eu/xsd/xroad.xsd" xmlns:iden="http://x-road.eu/xsd/identifiers" xmlns:dhl="http://producers.dhl.xrd.riik.ee/producer/dhl">
   <soapenv:Header>
      <xro:protocolVersion>4.0</xro:protocolVersion>
      <xro:id>64a3ddbd-1620-42c4-b2fe-60b854c2f32f</xro:id>
      <xro:service>
         <iden:xRoadInstance>ee-dev</iden:xRoadInstance>
         <iden:memberClass>GOV</iden:memberClass>
         <iden:memberCode>70006317</iden:memberCode>
         <iden:subsystemCode>dhl</iden:subsystemCode>
         <iden:serviceCode>getSendingOptions</iden:serviceCode>
         <iden:serviceVersion>v1</iden:serviceVersion>
      </xro:service>
      <xro:client>
         <iden:xRoadInstance>ee-dev</iden:xRoadInstance>
         <iden:memberClass>GOV</iden:memberClass>
         <iden:memberCode>40000001</iden:memberCode>
         <iden:subsystemCode>DHX</iden:subsystemCode>
      </xro:client>
   </soapenv:Header>
   <soapenv:Body>
      <dhl:getSendingOptions>
         <keha></keha>
      </dhl:getSendingOptions>
   </soapenv:Body>
</soapenv:Envelope>

5) Käivitada päring ja kontrollida, et vastus ei oleks HTTP viga ega SOAP-ENV:Fault viga.

Vaata täpsemalt DHX adapterserveri kasutusjuhendist WSDL asukohad ja SoapUI testimine.

This site is open source. Improve this page.