1. Introduktion
1.1. Formål
Formålet med dette dokument er at beskrive, hvordan et udviklingsmiljø, til videreudvikling af NAP ref-implementation, skal sættes op, samt hvordan koden deployes og testes.
1.2. Sammenhæng med øvrige dokumenter
Dette dokument er en del af den samlede dokumentation for NAP Ref.impl.
Dokumentet er udformet, så det i videst muligt omfang opfylder sit formål uafhængigt af de øvrige dokumenter.
Ønskes mere information omkring arkitektur og design findes dette på NAP Ref.Impl. - Design og Arkitektur beskrivelse.
Hvis der er behov for yderligere dokumentation omkring hele NAP platformen, henvises til NAP Platform - Guide til anvendere.
1.3. Forudsætninger
Software requirements:
| Software | Version |
|---|---|
| Java | 8 |
| Docker Engine | 18.02.0+ |
| node | 10+ |
Det lokale udviklingsmiljø er opsat med docker-compose.
nap-reference-web og nap-reference-facade ligger som repositories på svn.nspop.dk. Disse skal hentes for anvende de foreslåede compose-setup.
Derudover kræves et docker netværk kaldet nap_net. Hvis dette ikke allerede er lavet kør `docker network create nap_net`.
Trafik på localhost:8080 skal routes igennem en lokal reverse-proxy https://svn.nspop.dk/svn/components/nap/nap-compose/, som også er på docket netværket nap_net og eksponeret på port 8080 på localhost.
Således bliver nap-ref-facade tilgængelig på http://localhost:8080/reference/ og nap-refence-web på http://localhost:4400/.
Det meste funktionalitet af Nap-Ref-web kræver, at den er framet i en værtsapplikation.
For at gøre dette, skal opsætning for nap-java-host, nap-lobby-web, nap-admin køres parallelt (NAP Platform - Guide til anvendere).
1.4. Nap-reference-web
1.4.1. Funktionalitet
Nap-ref-web skal illustrere brugen af nap-typescript-sdk og nap-angular-sdk, anvendelse af samtlige versioner af eventkataloget, og demonstrere et projekt, der lever op til NSP husregler for webløsninger.
1.4.2. Udviklingsmiljø
Installer dependencies med `npm install` i rodfolderen.
Under compose folderen findes en compose fil til udvikling.
For at starte en webpack dev server i docker køres `docker-compose build && docker-compose up` fra compose/development.
Developper setuppet volume mapper ./src folderen, hvilket betyder, at ændringer i kildekoden bliver compilet 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.
Servicen benytter sig af nap-angular-sdk og nap-typescript-sdk og er udviklet til at være indlejret i et værtssytem (eksempelvis nap-java-host), hvor den får alt sin kontekst.
Det meste funktionalitet er bundet op på denne kontekst.
1.4.2.1. Konfiguration
Nap-reference-web benytter sig af Angular's environmental variable til at loade en af følgende konfigurations filer fra configurations.service.ts:
- configurations.json
- configurations-dev.json
Disse konfigurationsfiler indeholder urler til facaden, og er samtidig de konfigurerbare parametre af applikationen
Key | Value |
|---|---|
| appointmentsEndpoint | nap-reference-facades aftale endpoint |
| serverUrl | Roden til nap-reference-facade |
| logOutEndpoint | nap-reference-facades oiosaml logout endpoint |
1.4.2.2. Serverless opsætning
Det kan være en fordel at køre uden om nap-ref-facade, da den har en afhængighed til dokumentdelingsservicen på test1.
For at køre serverless skal `--configuration=mock` tilføjes startkommandoen i compose filen i compose/development/.
Alle kald resulterer nu i en indlæsning af ressourcer fra assets/.
1.4.2.3. Debug
Hvis nap-reference-web køres i serverless mode, kan den med fordel åbnes i chrome/firefox og debugges som vanligvis derfra.
Hvis den åbnes i nap-java-host, er den eneste debugging mulighed. consol.logs(). Disse statements printes til konsole vinduet af hosten, som kan toggles i toppen.
1.4.3. Byg
For at bygge projektet køres `npm run build`.
For at køre et produktionsbyg køres `npm run build-prod`.
1.4.4. CI
Projektet gøres klar til release ved
- rette versions-nummeret i packages.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-reference-web/trunk https://svn.nspop.dk/svn/components/nap/nap-reference-web/tags/release-1.0.0rc8
Jenkinsfilen beskriver en pipeline med install, test og build, der køres i NSPs node-chrome image, for at kunne afvikle test i en headless chromium browser.
Jenkins bygger og deployer i snapshot versioner af NSPs wildfly container. Dette byg kan testes ved at køre `docker-compose up` i compose/test.
1.4.5. Test og Coverage
For at køre unit-tests med Karma kør `npm run test`. Det kører alle unit tests i en headless chromium browser.
Istanbul generer en coverage rapport placeret i /coverage.
Eventuelle fejl printes til STOUT.
1.4.6. Linting
Der kan køres linting med eslint med `npm run lint`.
Eventuelle fejl printes til STOUT.
1.4.7. Dokumentation
Der kan generes dokumentation tsdoc med kommandon `npm run doc`
1.5. Nap-reference-facade
1.5.1. Udviklingsmiljø
Installer dependencies med `mvn install` i rodfolderen.
Under compose folderen findes forskellige compose filer til udvikling, test og release.
Vær opmærksom på kun at køre en service ved navn napreffacade. Stop derfor altid servicen og kør `docker-compose down`, når der skal skiftes setup eller deployes nye kodeændringer.
For at starte en wildfly server til udvikling køres `docker-compose build --no-cache && docker-compose up´ fra compose/development. Denne kommando skal køres hver gang der ønskes et nyt deploy med kode ændringer.
Developper setuppet sørger for at kopier target/nap-ref-facade.war og konfigurationerne fra compose/configuration over i NSP's wildfly image. Mere information om konfigurering kan læses på NAP Ref.Impl. - Driftsvejledning.
Applikationen kan nu nåes internt i docker på netværket nap_net på http://napreffacade:8080 og på nap-ref-facade på http://localhost:8080/reference/ hvis nap-compose reverse proxy, står foran som nævnt ovenfor.
1.5.1.1. Debugging
i compose/development sættes en debug port samt oiosaml.home.
Der kan attaches en Jvm debugger på localhost:8788 med `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8788`
1.5.2. Byg
For at bygge projektet kan køres `mvn compile`.
1.5.3. Test og Coverage
JUnit anvendes til implementering af unit tests.
Der er kontinuert 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.
integration tests kan afvikles ved at køre : `mvn test P-integrationstest"
Eventuelle fejl printes til STOUT.
1.5.4. Dokumentation
Kodedokumentation følger gængs standard for JAVA dokumentation.
1.5.5. Ci
Nap-reference-facade gøres klar til release med mvn release:prepare
Jenkinsfilen beskriver en pipeline med install og tests, der køres i NSPs java image.
Jenkins bygger og deployer i snapshot versioner af NSPs wildfly container.