Indholdsfortegnelse

Opsætning af udviklingsmiljø

Alt koden kan findes i følgende Subversion repository:

https://svn.nspop.dk/svn/components/sorus

Koden kan derefter importeres som projekt i en ønsket IDE (som Eclipse eller IntelliJ), der er ingen eksplicit grund til at skulle bruge en bestemt.

Projektet bygges af Maven, og er lavet til at køre under Java 8 og Wildfly 8.

Det anbefales også at installere Docker, men det er ikke strengt nødvendigt.

Beskrivelse af kodens struktur

Opdater servicen har følgende moduler:

...

Introduktion

Formål

Formålet med dette dokument er at beskrive hvordan et udviklingsmiljø, til videreudvikling af NAP platform services, skal sættes op, kodens struktur, samt hvordan koden bygges, deployes og testes.

Forudsætninger

Krav til software:

Generelt om udviklingsmiljø for projekterne

Det lokale udviklingsmiljø på projekterne er opsat med docker-compose.

For at kunne køre de compose filer, der bliver beskrevet nedenfor, kræves et docker netværk kaldet nap_net. Hvis dette ikke allerede er lavet kør "docker network create nap_net".

I hvert projekt ligger der en compose mappe, hvori der findes forskellige compose filer til udvikling, test og release.

Udvikling

Vær opmærksom på kun at køre en service af samme navn, fx kun køre en nap-test-web. Hvis der skiftes setup, stop altid servicen og kør "docker-compose down".

Der udstilles ingen porte på docker-hosten, og alt trafik routes således igennem en lokal reverse proxy (NAP Compose), som også er på Docker netværket nap_net og eksponeret på port 8080 på localhost.

For at starte reverse proxyen, hentes NAP Compose fra SVN, hvorefter docker-compose filen ligger i httpd mappen, som startes med "docker-compose up". 

Ved hhv nap-lobby-web og nap-test-web, bliver ./src folderen "volume-mappet", hvilket betyder, at ændringer i kildekoden bliver kompileret og deployet med det samme. 

Hvis dependencies ændres skal containeren bygges igen, ellers er det fremover nok at køre `docker-compose up` når services skal startes.

Test

Jenkins bygger og deployer i snapshot versioner af NSPs wildfly container. Dette byg kan testes ved at køre at `docker-compose up` i compose/test. 

Applikationen kan nåes på samme url som ovenfor. 

Release

Bruges udelukkende i produktions øjemed.

Generelt om release-procedure for projekterne

De to typer udviklingsprojekter tagges på forskellig vis inden release.

Såfremt det er nødvendigt at producere en release-kandidat, der skal på et test-miljø, gør en begrænsning i driftsleverandørens automatiserede håndtering, at release-navnet kun må indeholde én bindestreg, dvs. navnet bør være på formen

komponentnavn-1.0.2rc3

eller

release-1.0.2rc3.

Facade-projekter

Java-projekterne gøres klar til release med mvn release:prepare

Web-projekter

Typescript-projekterne gøres klar til release ved at

• rette versions-nummeret i package.json
• køre npm install
• kopiere trunk til tags-mappen, fx
  svn cp -m "<fantastisk commit-kommentar>" https://svn.nspop.dk/svn/components/nap/nap-administration/trunk https://svn.nspop.dk/svn/components/nap/nap-administration/tags/release-1.0.0rc8

nap-lobby-web

Indeholder et angular projekt, der har til formål at vise projekter som det givne LPS system har rettigheder til. Projektet bruger standard strukturen for et Angular projekt, dvs. alt koden ligger inde i src/ mappen. 

Nap-lobby-web gør brug af nap-administration backenden, til at hente de projekter der er til rådighed.

Funktionalitet

Projektet har tre faner "Projekter", "Administrer" og "hjælp". 

Projekter viser alle de projekter, som der er rettigheder til. Hvert projekt har titel, samt et versions nummer. Hvert projekt kan foldes ud ved at trykke på "mere", som så viser den tilknyttet web-app. Web-app'en viser titel, beskrivelse, version, udgivelses dato, url den ligger på, samt hvilke versioner af event kataloget den understøtter. 

Administrer viser alle projekterne og giver mulighed for at oprette nye eller redigere i eksisterende projekter.

Hjælp beskriver, hvad applikations formål, samt et link til at oprette en support sag. 

Udviklingsmiljø

Installer afhængigheder

Installer dependencies ved at køre "npm install --registry https://nexus.nspop.dk/nexus/repository/nsp-npm/"

Udviklingserver

For at starte en web pack dev server i docker køres "docker-compose build && docker-compose up" fra compose/development mappen.

Standalone (I browser)

Da nap-lobby-web bruger nap-administration som backend til at vise projekterne skal denne service startes først. Se  nap-administration.

Forudsat at nap-administration er startet som standalone og nap-compose er opsat som i 1.3.1 - Udvikling kan applikationen kan nu nåes på  http://localhost:8080/lobby.

Når du bliver redirected til en login skal bruger navnet Lars blot indtastes

SBO (gennem nap-java-host)

Ønskes Lobbyen teste i gennem nap-java-host skal nap-adminstration startes  med sikker-browser-opstart konfiguration. Se i nap-administration.

Hvis man ikke vil gøre brug af rigtige data, kan den "mockes" væk, således der vises dummy projekter. Dette kunne være for at se, hvordan det vil se ud hvis der var mange projekter tilføjet. Dette kan gøres ved at køre "npm run start:mock" hvis det køres lokalt, ellers kan der i compose/development ændres i docker-compose.yml "Command" parameter, hvor der tilføjes "--configuration=mock"

CI

Jenkins filen beskriver jenkins pipelinen.

NapLobbyWeb-build - bygger nap-lobby-web

NapAdmin-build - bygger nap-admin. I denne pibeline kan det vælges at bygge nap-lobby-web, hvis dette ønskes inkluderet.

NapAdmin- push snapshot - bygger nap-lobby-web og lægger bygget ind i roden af nap-admin samt pusher til NSP's docker registry.

Byg

Kør "npm run build" for at bygge projektet. Dette giver et output i dist/ folderen. Brug "npm run build-prod" for et produktionsbyg.

Linting

Kør "npm run lint" for linting, output kommer i konsollen

Test

Kør "npm run test" for at afvikle unit tests - output vil ligge I coverage/ mappen. 

Dokumentation

For at generere dokumentation til koden, kør "npm run doc". Dokumentation ligger i docs/ mappen.

nap-test-web

Indeholder et angular projekt, der har til formål at være test-platform for værtssystemsudvikler.

Funktionalitet

Projektet har til hensigt at teste der kan sendes og modtages beskender igennem NAP sdk'erne.

Den implementere det fulde eventkatalog fra NAP SDK - Guide til anvendere.

Der er separate tests cases, som kan køres enkeltvis eller samlet.  

Udviklingsmiljø

Installer afhængigheder

Installer dependencies ved at køre "npm install --registry https://nexus.nspop.dk/nexus/repository/nsp-npm/"

Udviklingserver

For at starte en web pack dev server i docker køres "docker-compose build && docker-compose up" fra compose/development mappen.

Applikationen kan nu nåes  http://localhost:8080/nap/test/web/, hvis nap-compose reverse proxy er opsat som beskrevet tidligere.

CI

Jenkins filen beskriver jenkins pipelinen.

NapTestWeb - build - bygger nap-test-web

NapTestWeb - push release candidate - pusher en release kandidat til NSP's docker registry

NapTestWeb - push snapshot - pusher en snapshot til NSP's docker registry

NapTestWeb - push release - pusher et release til NSP's docker registry

Byg

Kør "npm run build" for at bygge projektet. Dette giver et output i dist/ folderen. Brug "npm run build-prod" for et produktionsbyg.

Linting

Kør "npm run lint" for linting.

Dokumentation

For at generere dokumentation til koden, kør "npm run doc". Dokumentation ligger i docs/ mappen.

nap-administration

nap-administration fungerer som den administrative service for NAP projekter og webapplikationer. 

Funktionalitet

nap-administration indeholder 3 REST services for projekter, webapplikationer og session. 

Desuden håndteres i denne app de enkelte vært-/ LPSsystemers projektrettigheder. 

Udviklingsmiljø

Installer afhængigheder

Installer dependencies ved at "mvn install". 

Udviklingserver

Nap-administration kan startes med mulighed for login via SBO eller standalone.

Understøttelse af  SBO igennem nap-java-host

Default opsætning er, at der logges ind via nap-java-host. Derfor skal en wildfly server til udvikling herigennem køres "docker-compose build && docker-compose up" fra compose/development mappen.

Applikationen kan nu nåes internt i docker på netværket nap_net på  http://napadmin:8080 eller  på http://localhost:8080/lobby hvis nap-compose reverse proxy er opsat som i 1.3.1 - Udvikling.

Opstart af login via fake iDP

For at understøtte login via fake iDP skal oiosaml konfigurationen for localhost-standalone volumemappes.

Dette gøres ved at indkommentere denne konfiguration i development/docker-compose.yml og samtidig udkommentere linjen ovenfor for SBO.

Derefter kan en wildfly server til udvikling herigennem køres "docker-compose build && docker-compose up" fra compose/development mappen.

CI

Jenkins filen beskriver jenkins pipelinen.

Nap-administration bygges på NSP's Jenkins server via følgende jobs.

NapLobbyWeb-build - bygger nap-lobby-web

NapAdmin-build - bygger nap-admin. I denne pibeline kan det vælges at bygge nap-lobby-web, hvis dette ønskes inkluderet.

NapAdmin- push snapshot - bygger nap-lobby-web og lægger bygget ind i roden af nap-admin samt pusher til NSP's docker registry.

NapAdmin - push release - laver et release af nap-admin og pusher til NSP's docker registry.

Test

JUnit anvendes til implementering af unit tests. Der er løbende gennemført unit tests på alle komponenter i projektet.
Unit tests kan afvikles ved at køre: `mvn test` og Coverage rapport generes med maven-surefire og publiceres med jacoco.

Dokumentation

For at generere dokumentation til koden, kør "npm run doc". Dokumentation ligger i docs/ mappen.

Debugger

Debugging er slået til som default, en JVM debugger kan attaches  med `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8787`

Konfiguration

Alt konfiguration foregår ved at loade filer fra wildfly modulet dk.sds.nsp.nap.administration

De følgende konfigurationsfiler skal således volume mappes ind i modulet "dk/sds/nsp/nap/admin/main/" på applikations serveren (/pack/wildfly8/modules/ i docker).

nap-lobby-ds.xml

Disse filer bliver loadet ind på classpath wildfly når applikationen deployes.

Ved konfigurationsændringer skal wildfly serveren genstartes.

Konfiguration af oiosaml sker i filerne "compose/configuration/oiosaml". 

Der findes en konfiguration til localhost-sbo/ localhost-standalone/ localhost-test1-sbo / localhost-test2-standalone / test1 (test1 miljøet) / test2 (test2 miljøet). 

De forskellige konfigurationer adskiller sig primært for singleLogoutService i SPMetadata og iDpMetadata samt og service provider url i oiosaml-sp.properties. 

Oiosaml konfigurationerne skal ligeledes være tilgængelig i oiosaml.home under deployment (oiosaml.home sættes med JAVA_OPTS i compose filerne og er sat til /pack/oiosaml).

Persistence

Persitence.xml placeret i meta-inf definerer hibernate konfigurationen. Hvis der tilføjes nye tables, skal denne opdateres

Database

Datamodellen kan ses her i Data.

nap-host-java

nap-host-java er en tyk java klient. Den fungerer som et eksempel på et værtssystem, egnet som test-platform for gæstesystemudviklere, samt som et implementations eksempel for værtsystems- / LPSudviklere

Funktionalitet

For beskrivelse af funktionaliteten i nap-host-java, findes der mere information beskrevet i Guide til anvendere 

For at nap-host-java kan vise projekterne, er det vigtigt at nap-lobby-web er sat op til at køre som beskrevet i 3. Nap Lobby Web.

Udviklingsmiljø

Installer afhængigheder

Installer dependencies ved at "mvn install". 

Udviklingserver

For at starte applikationen køres main fra Launcher klassen.  

CI

Jenkins filen beskriver jenkins pipelinen.

Der kan laves snapshots og release-candidates fra jenkins.

Test

JUnit anvendes til implementering af unit tests. Der er løbende gennemført unit tests på alle komponenter i projektet.
Unit tests kan afvikles ved at køre: `mvn test` og Coverage rapport generes med maven-surefire og publiceres med jacoco.

Konfiguration

Nap-host-java konfigureres i nap-java-host.properties som pakkes med i classpath

Under hvert eneste modul ligger også en Dockerfile for at generere Docker images af hvert modul.

Opdater servicen er implementeret med Den Gode Webservice (DGWS), hvor at Seal.Java er brugt til at håndtere headers. Servicen er implementeret i Spring Boot. Biblioteker som leveres af Wildfly, bliver ikke inkluderet i den resulterende war fil.

To Maven plugins benyttes til at generere kode; cxf-codegen-plugin og jaxb2-maven-plugin. JAXB pluginet bliver brugt til at generere klasser ud fra specifikke XSD filer, imens at CXF pluginet bliver brugt til at generere klasser ud fra WSDL filer. Klasser genereret af CXF pluginet giver ikke nødgenvigvis en afhængighed af Apache CXF, men der er inkluderet et plugin i dette, som generere en override af toString() på samtlige genererede klasser, som er afhængig af et CXF specifikt bibliotek. Dette bør uden videre kunne fjernes uden tab af funktionalitet, men er praktisk i forhold til debugging.

Apache CXF benyttes til at håndtere JAX-WS klient implementationerne. Ligeledes benyttes Apache CXF til server implementationen af stub backend servicen.

Beskrivelse af test setup

Unittests

Unittests kan udføres ved at køre følgende Maven kommando:

mvn test

Hvis test coverage rapporten skal skrives, skal Maven's verify step også køres. I det tilfælde vil kommandoen se sådan ud:

mvn test verify

Coverage rapporten vil kunne findes under følgende lokation:

target/site/jacoco/index.html

Unittests kan indstilles ved at rette i filen:

src/test/resources/unit/sorus.properties

Alle test properties burde allerede være opsat som de bør være, og ingen konfiguration er nødvendigt.

Integrationstests

Integration tests kan udføres ved at køre følgende Maven kommando:

mvn verify -P integrationTests

Integration tests sker først på verify steppet, og laver valide forespørgelser mod en deployeret service. Det er rigtige forespørgelser mod en rigtig deployment, så fejl på grund af datas indhold kan opleves, selvom at selve formen er korrekt. For eksempel, der forsøges oprettet en SOR enhed med et CVR, som allerede eksisterer i systemet. Dette vil fejle, da CVR skal være unikt, også selvom at den tilhører en slettet/lukket enhed.

Integration tests kan indstilled ved at rette i filen:

src/test/resources/integration/sorus.properties

Alternativt kan properties sættes og/eller overskrives på kommando linien. Følgende er eksempel på at overskrive URL til applikationen:

mvn verify -P integrationTests -DargLine="-Dsorus.url=http://differenturl:8080/sor-opdatering"

Deployment

En war fik kan genereres ved at køre Maven kommandoen:

mvn package

Projektet er opsat efter guidelines beskrevet for NSP's CI/CD opsætning, som kan findes her NSP Continuous Integration & Delivery. Den docker-compose.yml fil som hører til development er den anbefale måde at lave en deployment af lokalt, da det opsætter et produktion-lignende miljø. Alle nødvendige databaser samt stub backenden vil blive opsat, og være klar til brug.

Alternativt kan servicen blive deployed på en lokal Wildfly server. Det anbefales at sætte denne op i forhold til hvordan imaget https://registry.nspop.dk/harbor/projects/4/repositories/playground%2Fnsp/tags/stable er defineret (Dockerfile er inkluderet i image). Filen SorUpdateService/target/sor-opdatering.war kopieres til standalone/deployment/ mappen i Wildfly. Ligeledes skal SorUpdateService/resources/sorus-ds.xml (som indeholder opsætning af datasource til whitelisting databasen) kopieres til standalone/deployment/ mappen, imens at SorUpdateService/resources/sorus.properties og SorUpdateService/resources/log4j-sorus.properties skal kopieres til standalone/configuration/ mappen i Wildfly.

Uanset hvilken måde deployment bliver foretaget på, så vil bemærkningen under SOR backend være relevant.

Bemærkninger

SOR backend

Der er en rigtig udvikling deployment af SOR backend servicen, men den kræver at deployment af opdater servicen kan nå sundhedsdatanettet (SDN). Stub backend servicen (som er del af denne kodebase) er udviklet blandt andet på grund af dette, og det anbefales primært at benytte den under udvikling og indledende integration test. Stub servicen genereres ud fra samme WSDL fil som den rigtig backend udstiller; denne skal dog opdateres manuelt lokalt, og kan findes i external/ mappen i roden af projektet.

Hvis ens udvikling setup er på SDN, og den rigtige backend kan benyttes, skal man være opmærksom på, at den udelukkende kan kontaktes på IPv6. Hostnavnet vil kunne resolves til en IPv4 adresse, men denne kan ikke bruges overhovedet. I skrivende stund vil Wildfly images for NSP blive opsat med -Djava.net.preferIPv4Stack=true i standalone.conf filen (standalone.conf.bat hvis det er sat op på Windows); det er vigtigt at denne switch bliver sat til false, da at den ubruglige IPv4 adresse vil få Wildfly til slet ikke at prøve IPv6 adressen.

Opdatering af XSD filer

Hvis der kommer opdatering af XSD filerne for backend servicen, så skal der opdateres to steder.

For hvor fra at klasserne for klient implementationen mod backenden, læses WSDL og XSD filer fra external/schema/sor. Det er også herfra at stub backenden genererer sine klasser fra, hvis denne benyttes.

For hvor fra at klasserne for server implementationen, læses WSDL filen fra SorUpdateService/src/main/webapp, og alle XSD filer er at finde under SorUpdateService/src/main/webapp/v3/schema.

Backenden genererer en WSDL fil med samtlige typer den benytter indlejret i. For at benytte dem for server implementationen af SORUS skal disse først kopieres ud i separate filer. Yderligere er backenden kun i stand til at sætte typen xs:dateTime på alle dato felter selvom at det bør kun være xs:date. Dette er en begrænsning i .NET som den rigtige backend er skrevet i, men der er ikke oplevet nogen fejl ved manuelt at ændre disse felter til xs:date.