KIH Database Systemdokumentation for KIH Databasen 12. september 2014 Side 1 af 20
Indholdsfortegnelse Indholdsfortegnelse Indledning Systemoverblik KIH Database applikationsserver Forudsætninger før installation Klargøring af database mv. før installation Deployment til Apache Tomcat 7 Overblik over log filer for KIH Databasen Overvågning af KIH Database server KIH Database monitoreringssnitflade Backup og restore af KIH Databasen Backup af Java EE web applikation Backup af database Restore af KIH Databasen Konfiguration af KIH Database Konfiguration af applikationen Konfiguration af applikations log output Dokumenthistorik Side 2 af 20
Indledning Dette dokument udgør den tekniske systemdokumentation for KIH Databasen. Systemdokumentationen indgår i den samlede KIH Database dokumentationspakke, hvis dele er beskrevet i KIH Database dokumentationsoverblik. Formålet med systemdokumentationen er at beskrive hvordan KIH Database platformen installeres, konfigureres og driftes. Dokumentet giver et overblik over konfigurationsfiler, log filer og andre relevante objekter. Systemdokumentationen tager udgangspunkt i, at en række komponenter er tilgængelige. De væsentligste af disse er et operativsystem, en database og en Java EE servlet container. Systemoverblik Dokumentet KIH Database Arkitektur og design beskriver den overordnede arkitektur for KIH Databasen. I den følgende gengives dele af arkitekturbeskrivelsen, med fokus på de elementer der er relevante for systemdokumentationen. KIH Database platformen består af en Grails baseret serverapplikation, som afvikles i en Java EE web container. Nedenfor er den overordnede principielle systemarkitektur illustreret. Side 3 af 20
I illustrationen vises en central KIH Database applikationsserver hvor KIH Database web applikationen er installeret. Serveren udstiller en web baseret brugergrænseflade til administratorer, som de anvender via en browser. Til systemintegration udstilles en XML baseret web service, som eksterne systemer anvender til at indberette og hente data med. KIH Database applikationsserveren anvender en standard SQL database som datalager. Løsningen er testet med H2, MySQL 5 og SQL*Server 2008. I det følgende antages at en Apache Tomcat 7 web container anvendes på serversiden. KIH Database web applikationen er også testet på JBoss, og bør fungere uden store problemer i 1 følgende Java EE Containere som er supporteret af Grails 2.3.11. Tomcat 7 Tomcat 6 SpringSource tc Server Eclipse Virgo GlassFish 3 GlassFish 2 Resin 4 Resin 3 JBoss 6 1 Se http://grails.org/doc/2.1.0/guide/single.html#supportedjavaeecontainers Side 4 af 20
JBoss 5 Jetty 7 Jetty 6 IBM Websphere 7.0 IBM Websphere 6.1 Oracle Weblogic 10.3 Oracle Weblogic 10 Oracle Weblogic 9 KIH Database applikationsserver KIH Databasens applikationsserver er en Java EE web applikation, udviklet i frameworket Grails 2.3.11. I det følgende beskrives hvordan en Java EE web applikation (WAR fil) bygges og installeres på en applikationsserver. Selve installationen af WAR filen i Java EE applikationsserveren afhænger af hvilket operativsystem, samt hvilken applikationsserver og databaseteknologi, man vælger at anvende. I det følgende eksempel anvendes version 7 af Apache Tomcat Servlet Container en som applikationsserver, MySQL 5 som datalager og OS X 10.7 som operativsystem. Forudsætninger før installation Før installation af KIH Database server forudsættes følgende: 1. Adgang til en, to eller flere fysiske eller virtuelle maskiner med operativsystem installeret. Det er op til en konkret designbeslutning i opsætningen af systemet, om man vil afvikle applikationsserver og database på separate maskiner. I det følgende antages at to separate maskiner anvendes. 2. På systemets applikationsserver skal en Java EE webcontainer være installeret. F.eks. JBoss eller Apache Tomcat 7. Applikationsserveren skal anvende Java 6. Java 7 er ikke understøttet. 3. På systemets databaseserver skal f.eks. MySQL eller SQL*Server være installeret. 4. En WAR fil med KIH Database web applikationen, bygget til det konkrete miljø skal være tilgængelig Side 5 af 20
Kompilering og byg af en WAR applikation er beskrevet nærmere i dokumentet KIH Database Guide til videreudvikling. Kort beskrevet, skal et miljø (environment) defineres i web applikationen (gøres af systemets udviklingsteam). Efterfølgende skal der bygges en WAR fil til det konkrete miljø. Hvis et miljø med navnet osxtest f.eks. er defineret, kan war filen bygges med kommandoen: grails Dgrails.env=osxtest war Klargøring af database mv. før installation I det følgende beskrives hvordan KIH Databasen installeres (deployes) til en Apache Tomcat 7 web container. For installation i andre Java EE web containere, f.eks. JBoss, henvises til den sektion i manualen for den konkrete web containere, som beskriver installation af web arkiver (WAR filer). Før installation af web arkivet skal systemets database være installeret. Hvis MySQL anvendes kan dette f.eks. ske ved at installere MySQL, og efterfølgende oprette en database, og en KIH Database bruger, med kommandoerne i nedenstående boks: create database kihdb character set utf8; GRANT SELECT, INSERT, UPDATE, CREATE, DELETE, DROP, ALTER, INDEX on kihdb.* TO ' kihdb@'localhost' IDENTIFIED BY 'kihdb'; flush privileges; Husk at udskifte brugernavn og adgangskode i ovenstående. Når databasen er installeret skal der oprettes en konfigurationsfil, hvorfra web applikationen henter sin konfiguration. På Windows placeres konfigurationsfilen i biblioteket: c:\kihdatamon\settings\kihdb config.properties På Unix baserede systemer (f.eks. Linux eller OS X) placeres filen i biblioteket: ${userhome}/.kih/kihdb config.properties Hvor ${userhome} angiver home biblioteket for den bruger som web containeren kører under. Hvis filen ønskes placeret andetsteds, skal dette ændres i systemets kildekode. Side 6 af 20
Nedenfor to eksempler på KIH Database konfigurationsfiler. Én hvor web applikationen anvender en MySQL database som datalager, og én hvor web applikationens datalager er en Microsoft SQL*Server. Eksempel på KIH Database konfigurationsfil med MySQL database: # Common settings #datasource.dbcreate = update datasource.pooled = true #datasource.logsql = false ## MYSQL DB datasource.dialect = dk.silverbullet.kihdb.util.mysqlinnodbdialect datasource.driverclassname = com.mysql.jdbc.driver datasource.username = kihdb datasource.password = kihdb datasource.url = jdbc:mysql://10.0.0.1:3306/kihdb Eksempel på KIH Database konfigurationsfil med SQL*Server database (OBS: Hvis katalog ikke anvendes på SQL*Server fjernes denne linie): # Common settings #datasource.dbcreate = update datasource.pooled = true #datasource.logsql = false # SQL Server DB datasource.driverclassname = net.sourceforge.jtds.jdbc.driver datasource.username = kihdb datasource.password = kihdb datasource.url = jdbc:jtds:sqlserver://10.0.0.1:1433:kihdb datasource.dialect = dk.silverbullet.kihdb.util.sqlserverdialect hibernate.default_schema = dbo hibernate.default_catalog = kihdb Konfigurationsfil parameteren datasource.dbcreate, mapper til Grails standard databaseopsætnings (dbcreate) parameter og kan antage værdierne i nedenstående tabel. I et produktionssetup, anbefales det at fjerne parameteren helt, eller sætte den til værdien validate, da der ellers er risiko for, at systemet vil forsøge at overskrive dets database når det startes/genstartes. Hvis man i forbindelse med installationen af KIH Databasen ønsker at oprette tabeller mv. i systemets relationelle database, kan det gøres ved at starte systemet med værdien sat til: Side 7 af 20
datasource.dbcreate = create. Efterfølgende når systemet er startet og tabelstruktur er oprettet skal parameteren ændres til f.eks. datasource.dbcreate = validate. En bedre metode til oprettelse af tabeller er, at systemets udviklere danner et tabel oprettelsesscript (DDL). Og at systemet enten konfigureres med en tom datasource.dbcreate eller med datasource.dbcreate = validate. dbcreate værdi create update validate Betydning Ved opstart af web applikationen nyoprettes tabeller og andre databaseobjekter. Ved opstart af web applikationen oprettes tabeller og andre databaseobjekter som ikke i forvejen eksisterer i databasen. Ved opstart af web applikationen validerer applikationen om alle nødvendige databaseobjekter er tilstede. Hvis dette ikke er tilfældet kan applikationen ikke starte (deployes) og logger i stedet en fejl til en dens log filer. Tom værdi. Systemet antager at alle nødvendige databaseobjekter er til stede, men gør ikke noget for at undersøge om det er tilfældet. Deployment til Apache Tomcat 7 Når database og konfigurationsfiler er klargjort kan web applikationen (WAR filen) installeres på systemets applikationsserver. På Apache Tomcat sker dette ved at kopiere war filen (f.eks. kih_database.war) til Tomcat serverens webapps bibliotek. På OS X og Linux kan dette gøres i en shell med kommandoen: cp kih_database.war ${TOMCAT_HOME}/webapps/ Afhængigt af hvordan Apache Tomcat serveren er konfigureret, vil ovenstående kommando installere KIH Database web applikationen, så dens rod kontekst er kih_database, når man åbner den fra en web browser, d.v.s.: http://<server_url>/kih_database Hvis man i stedet ønsker, at applikationen skal installeres så brugere ikke skal angive en rod kontekst kan det gøres ved at omdøbe war filen til ROOT.war når den kopieres til webapps biblioteket: Side 8 af 20
cp kih_database.war ${TOMCAT_HOME}/webapps/ROOT.war Når applikationen installeres navngivet ROOT.war, forstår Tomcat det sådan, at den skal udbyde applikationen uden en rod kontekst. D.v.s. på adressen: http://<server_url> Efter installation, verificeres om serveren er korrekt installeret ved at overvåge om den skriver fejl til sine log filer, og ved at åbne applikationen i en web browser. Nedenfor er vist et eksempel på, hvordan applikationens log ind side ser ud på miljøet kihdb test, når den er deployet som ROOT.war. Overblik over log filer for KIH Databasen KIH Database server er konfigureret til at sende sine logs til Tomcats standard logbibliotek. Dvs.: <TOMCAT>/logs Side 9 af 20
Hvis systemet skal skrive log filer til en anden lokation, skal dette konfigureres af udviklingsorganisationen (i filen Config.groovy ). I standard opsætningen logger KIH Database webapplikationen til filen kihdb.log. Som standard er applikationen konfigureret til at danne en ny log fil på dagsbasis. D.v.s. nyeste log fil er filen kihdb.log. Ældre log filer omdøbes, så de efter kihdb.log tilføjes datoen for de logninger filen indeholder. F.eks.: Filnavn Beskrivelse kihdb.log Seneste logninger fra KIH Database web applikationen kihdb.log.2013 04 30 Logninger fra 30. april 2013 kihdb.log.2013 04 29 Logninger fra 29. april 2013 kihdb.log.2013 04 28 Logninger fra 28. april 2013 Logfilen bør ikke indeholde fejl logninger. Disse er kendetegnet ved at ordet ERROR indgår i en lognings linie. Overvågning af KIH Database server I dette afsnit beskrives den snitflade KIH Database serveren stiller til rådighed for anvendelse i en driftsmæssig overvågning af platformen. En samlet overvågning af systemet bør også omfatte overvågning af systemets processer samt databaseserver og diskplads m.v. Hvilke processer der skal være kørende på systemet afhænger af hvilken Databaseteknologi og hvilken Java EE webcontainer systemet anvender. Der henvises derfor til dokumentationen for de konkrete produkter. KIH Database monitoreringssnitflade KIH Databasen udstiller en simpel web side, som kan anvendes til overvågning af serverens tilstand fra enten et overvågningssystem eller f.eks. en browser. Web siden udstilles på adressen: http(s)://<kih DATABASE URL>/<ROD KONTEKST>/isAlive Når siden kaldes, undersøger systemet om det er korrekt kørende og om det har mulighed for at skabe forbindelse til dets database. I nedenstående skærmbillede vises et eksempel på siden, som den ser ud når alt er fungerende: Side 10 af 20
Der er fire værdier på siden, som beskrives i følgende tabel: Tekst responsetext runningversion environment isdatabasealiv e Beskrivelse Svarer I m alive! hvis systemets applikationsserver er fungerende. Angiver hvilken version af KIH Databasen der er installeret på serveren. Angiver hvilket miljø serveren er konfigureret som (eksempelvis test, devel eller production) Angiver om applikationsserveren (f.eks. Tomcat) kan oprette en forbindelse til systemets SQL database. Mulige svar er: Yes. eller No.. For at have et fuldt fungerende system, skal responsetext være I m alive! og isdatabasealive være Yes.. Backup og restore af KIH Databasen I det følgende angives anbefalinger for backup/restore strategier for KIH Database applikationen. Den konkrete strategi og fremgangsmåde afhænger af hvilke teknologier en konkret installation anvender. Backup af Java EE web applikation KIH Database server applikationen gemmer alle data i sin database. Det bør derfor ikke være nødvendigt at lave løbende backup af applikationsserverens filsystem. Det anbefales derfor, at der efter installation laves en initiel backup af maskinen serveren er installeret på, og at der løbende tages backup af serverens konfigurationsfil (beskrevet i tidligere afsnit). Hvorvidt der udføres backup af web applikationens log filer, besluttes i forbindelse med den konkrete installation. Backup af database Det anbefales at der etableres løbende backup af systemets database, således data ikke kan gå tabt ved evt. systemnedbrud. Side 11 af 20
Restore af KIH Databasen Hvis der er sket en hændelse, som medfører at det er nødvendigt at lave restore af hele eller dele af KIH Database installationen, anbefales følgende overordnede fremgangsmåde: 1) Kontrollér, at alle systemets applikationsservere, og andre systemer som skriver til systemets database, er standsede 2) Gendan systemets database 3) Start databaseserveren 4) Lav restore af systemets applikationsservere (eller start dem igen) Side 12 af 20
Konfiguration af KIH Database Følgende kan konfigureres for KIH databasen. Applikationen skal genstartes før ændringerne træder i kraft. Der kan i dag konfigureres: 1. Applikationen 2. Applikationens log output. Konfigurationen skal placeres i et af følgende biblioteker: Platform Bibliotek Windows c:/kihdb/settings Unix/Linux/mac $HOME/.kih Hvor $HOME referere til brugeren s home bibliotek, som afvikler applikationen. F.eks, tomcat brugeren. Side 13 af 20
Konfiguration af applikationen Konfiguration af applikationen gøres i en property fil (standard Java property fil), som hedder: kihdb config.properties. Værdi Default værdi Forklaring datasource.drivercl assname net.sourceforge.jtds.jdbc.dri ver Hvilke JDBC klasse skal anvendes for at snakke med applikations database datasource.username <username> Username til database datasource.password <password> Password til database datasource.url datasource.dialect hibernate.default_s chema = hibernate.default_c atalog = jdbc:jtds:sqlserver:#<ip>:<po rt>:<db> dk.silverbullet.kihdb.util.sq LServerDialect dbo KIHTest JDBC URL til Database. Eksempel viser til en MS SQL server Hvilken hibernate dialect anvendes. Følgende kan anvendes: dk.silverbullet.kihd b.util.sqlserverdial ect dk.silverbullet.kihd b.util.mysqlinnodbdi alect dk.silverbullet.kihd b.util.h2dialect Hvilket database schema der skal anvendes Hvilket default katalog, som skal anvendes datasource.dbcreate validate Se Grails Datasource dokumentation af opsætning for dbcreate. Anbefalet værdi i produkton er validate datasource.pooled true Se Grails Datasource dokumentation. datasource.logsql False Se Grails Datasource dokumentation. Side 14 af 20
seal.sts.url <URL til NSP STS> URL til STS på NSP, som anvendes til validering af SOSI id kort seal.cvr 19343634 Opsætning af CVR nummer til brug for oprettelse af ID kort i forbindelse med kommunikation med Stamdata Service og NPI. seal.systemname SOSITEST Systemname til brug for oprettelse af SOSI idkort seal.federation.typ e test Hvilken type SOSI federation anvendes. Der kan anvendes følgende værdier: test for test systemer production for produktionssystemer seal.vault.type classpath Hvilken type af søgning skal der laves for at finde keystore, som indeholder certifikater til SOSI id kort oprettelse. Værdier er: classpath der søges efter keystore i classpath file Der søges i filsystemer efter keystore seal.vault.password <password til keystore> Password til keystore seal.vault.path <sti til keystore> Sti til keystore seal.check.disable true Skal der DGWS check overholdes. Værdier: true DGWS sikkerhed håndhæves false DGWS check håndhæves ikke hsuid.check.disable true Skal der HSUID header check overholdes. Værdier: Side 15 af 20
registercitizens.ru n registercitizens.re peatintervalmillis detectmissingdocume nt.run detectmissingdocume nt.repeatintervalmi llis kihdb.xds.documentr epository.oid kihdb.xds.source.oi d xds.documentregistr y.url xds.documentregistr y.servicename xds.documentregistr y.updateregistry true HSUID check håndhæves false HSUID check håndhæves ikke true Hvor vidt job til registering af patienter i Sundhed.dk s Personaliseringsindeks skal afvikles eller ej. 180000 Hvor tit skal jobbet afvikles. Værdien angives i milisekunder. true Styre hvor vidt jobbet, som checker om der er generet manglende PHMR dokument (og XDS metadata) for målinger i KIH Database skal afvikles 180000 Hvor tit skal jobbet afvikles. Værdien angives i milisekunder. 2.16.840.1.113883.3.4208.2.1 XDS OID som identificere KIH DB som Document Repository i XDS arkitektur. Se nedenstående tabel for værdier. 2.16.840.1.113883.3.4208.3.1 XDS OID som identificere KIH DB som Document Source i XDS arkitektur Se nedenstående tabel for værdier. <URL til NPI service> URL til NPI DocumentRegistry_Service false Service Navnet for NPI. Anvendes når KIH DB skal oprette service forbindelse Styre, hvorvidt KIHDB skal opdateret XDS Registry (NPI) Side 16 af 20
sundhed.dk.personal iseringsindex.url sundhed.dk.personal iseringsindex.servi cename sundhed.dk.personal iseringsindex.enabl ed sundhed.dk.applicat ion.id sundhed.dk.username sundhed.dk.password cpr.url <URL til sundhed.dk Personaliseringsindeks PersonaliseringsIndeksEndpoin tservice true URL til Sundhed.dk s PersonaliseringsIndex Service Navnet for PersonaliseringsIndex. Anvendes når KIH DB skal oprette service forbindelse Styre, hvor vidt KIH Database skal opdatere Personaliseringsindeks 532 Applikations ID, som identificerer KIH Database overfor Sundhed.dk s Personaliseringsindeks <username til sundhed s service> <password til sundhed s service> <URL til StamdataPersonLookup> Username til at forbinde til Personaliseringsindeks Password til at forbinde til Personaliseringsindeks URL til brug for CPR opslag OID er som identificere KIH Database som XDS Document Repository overfor NPI. Miljø OID KIHDB PROD 2.16.840.1.113883.3.4208.2.1 KIHDB STAG 2.16.840.1.113883.3.4208.2.2 KIHDB TEST 2.16.840.1.113883.3.4208.2.3 KIHDB INTEG 2.16.840.1.113883.3.4208.2.4 KIHDB DEVEL 2.16.840.1.113883.3.4208.2.5 OID er som identificere KIH Database som XDS Document Source overfor NPI. Miljø OID KIHDB PROD 2.16.840.1.113883.3.4208.3.1 KIHDB STAG 2.16.840.1.113883.3.4208.3.2 KIHDB TEST 2.16.840.1.113883.3.4208.3.3 KIHDB INTEG 2.16.840.1.113883.3.4208.3.4 KIHDB DEVEL 2.16.840.1.113883.3.4208.3.5 Side 17 af 20
Konfiguration af applikations log output Konfiguration af applikations log out gøres ved følgende (dog ikke påkrævet) fil: kihdb logging config.groovy Filen indeholder som default for produktion følgende settings: String logdirectory = "${System.getProperty('catalina.base')?: '.'}/logs" // Logging println "Setting up external log configuration" import grails.util.environment import org.apache.log4j.dailyrollingfileappender String commonpattern = "%d [%t] % 5p %c{2} %x %m%n" log4j = { appenders { console name: "stdout", layout: pattern(conversionpattern: commonpattern) appender new DailyRollingFileAppender( name: "kihdb", datepattern: "'.'yyyy MM dd", file: "${logdirectory}/kihdb.log", layout: pattern(conversionpattern: commonpattern)) } root { error 'kihdb', 'stdout' } error 'org.codehaus.groovy.grails.web.servlet', // controllers 'org.codehaus.groovy.grails.web.pages', // GSP 'org.codehaus.groovy.grails.web.sitemesh', // layouts 'org.codehaus.groovy.grails.web.mapping.filter', // URL mapping 'org.codehaus.groovy.grails.web.mapping', // URL mapping 'org.codehaus.groovy.grails.commons', // core / classloading 'org.codehaus.groovy.grails.plugins', // plugins 'org.codehaus.groovy.grails.orm.hibernate', // hibernate integration, 'org.codehaus.groovy.grails.commons.cfg', 'org.springframework', 'org.hibernate', 'org.apache', 'net.sf.ehcache.hibernate', 'grails.app.services.org.grails.plugin.resource', 'grails.app.taglib.org.grails.plugin.resource', 'grails.app.resourcemappers.org.grails.plugin.resource', 'grails.app.service.grails.buildtestdata.buildtestdataservice', 'grails.app.buildtestdata', 'grails.app.services.grails.buildtestdata', 'grails.buildtestdata.domaininstancebuilder', 'grails.app' Side 18 af 20
} info 'dk.silverbullet' For fuld debug af applikationen kan følgende anvendes: String logdirectory = "${System.getProperty('catalina.base')?: '.'}/logs" // Logging println "Setting up external log configuration" import grails.util.environment import org.apache.log4j.dailyrollingfileappender String commonpattern = "%d [%t] % 5p %c{2} %x %m%n" log4j = { appenders { console name: "stdout", layout: pattern(conversionpattern: commonpattern) appender new DailyRollingFileAppender( name: "kihdb", datepattern: "'.'yyyy MM dd", file: "${logdirectory}/kihdb.log", layout: pattern(conversionpattern: commonpattern)) } root { error 'kihdb', 'stdout' } error 'org.codehaus.groovy.grails.web.servlet', // controllers 'org.codehaus.groovy.grails.web.pages', // GSP 'org.codehaus.groovy.grails.web.sitemesh', // layouts 'org.codehaus.groovy.grails.web.mapping.filter', // URL mapping 'org.codehaus.groovy.grails.web.mapping', // URL mapping 'org.codehaus.groovy.grails.commons', // core / classloading 'org.codehaus.groovy.grails.plugins', // plugins 'org.codehaus.groovy.grails.orm.hibernate', // hibernate integration, 'org.codehaus.groovy.grails.commons.cfg', 'org.springframework', 'org.hibernate', 'org.apache', 'net.sf.ehcache.hibernate', 'grails.app.services.org.grails.plugin.resource', 'grails.app.taglib.org.grails.plugin.resource', 'grails.app.resourcemappers.org.grails.plugin.resource', 'grails.app.service.grails.buildtestdata.buildtestdataservice', 'grails.app.buildtestdata', 'grails.app.services.grails.buildtestdata', 'grails.buildtestdata.domaininstancebuilder', 'grails.app' info 'org.apache.cxf' Side 19 af 20
debug 'grails.app', 'dk.silverbullet' } Dokumenthistorik Version Dato 1.0 01 05 2013 1.2 12 09 2014 Initialer Ændring Initiel version LCH Opdateret til version 1.2 Side 20 af 20