Page History
...
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.
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.
Forudsætninger
Software requirements:
| Software | Version |
|---|---|
| Java | 8 |
| Docker Gerne nyesteEngine | 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 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`.
Trafik på localhost:8080 skal routes igennem en lokal reverse-proxy https://svn.nspop.dk/svn/components/nap/nap-compose/, som også er på også docket netværket nap_net og eksponeret på på port 8080 på localhost.
Således bliver nap-ref-web facade tilgængelig på http://localhost:8080/reference/ og nap/reference/web-refence-web på http://localhost:4400/.
Det meste funktionalitet af Nap-Ref-web kræver, at den er framet i en værts-applikationværtsapplikation.
For at gøre dette, skal opsætning for nap-java-host, nap-lobby-web, nap-admin køres parallelt (Platformsservices (NAP ) Platform - LeverancebeskrivelseGuide til anvendere).
Nap-reference-web
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.
Udviklingsmiljø
Installer dependencies med `npm install` i rodfolderen.
Under compose folderen findes forskellige composefiler en compose fil til udvikling, test og release.
Vær opmærksom på kun at køre en service ved navn naprefweb. Stop derfor altid servicen og kør `docker-compose down`, når der skal skiftes setup.
For at starte en webpack dev server i docker køres køres `docker-compose build && docker-compose up` fra compose/developdevelopment.
Developper setuppet volume mapper ./src folderen og konfigurationsfiler fra compose/configuration, 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.
Applikationen kan nu nåes http://localhost:8080/nap/reference/web/, hvis nap-compose (https://svn.nspop.dk/svn/components/nap/nap-compose/) reverse proxy, står foran som nævnt ovenfor, og ellers på http://Localhost:4600.
compose/release konfigurationen bruges udelukkende i produktions øjemed.
Konfiguration
configurations.json indeholder de konfigurerbare parametre af apllikatione
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.
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 |
Key | Value |
| AppointmentsEndpoint | Aftale endpoint |
| ServerUrl | Relative path til nap-reference-facade |
...
| logOutEndpoint | nap-reference-facades oiosaml logout endpoint |
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 bliver resulterer nu i en indlæsning af ressourcer fra assets/.
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.
Byg
For at bygge projektet kan projektet køres `npm run build`.
For at køre et produktionsbyg køres `npm run build:-prod`.
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 at `docker-compose up` i compose/test.
...
Istanbul generer en coverage rapport kommer placeret i /coverage.
Eventuelle fejl printes til STOUT.
Linting
Der kan køres linting med eslint med `npm run lint`.
Eventuelle fejl printes til STOUT.
Dokumentation
Der kan generes documentation dokumentation tsdoc med kommandon `npm run doc`
Nap-
...
reference-facade
Udviklingsmiljø
Installer dependencies med `mvn install` i rodfolderen.
Under compose folderen findes forskellige composefiler compose filer til udvikling, test og release.
...
For at starte en wildfly server til udvikling køres `docker-compose build --no-cache && docker-compose up´ fra compose/developdevelopment. Denne kommando skal køres hver gang der ønskes et nyt deploy af med kode ændringer.
Developper setuppet sørger for at kopier target/nap-ref-facade.war og konfigurationerne fra compose/configuration over i et image NSPS wildfly image.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/nap/reference/web/services/main hvis nap-compose reverse proxy, står foran som nævnt ovenfor.
Debugging
i compose/development sættes en debug port samt oiosaml.home.
Der kan attaches en Jvm debugger på localhost:8878 8788 med `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8788`
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.
Aplikationen kan nåes på samme url som ovenfor.
compose/release konfigurationen bruges udelukkende i produktions øjemed.
Byg
For at bygge projektet kan køres `mvn compile`.
...
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.
Dokumentation
Kodedokumentation følger gængs standard for JAVA dokumentation.
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
Jenkins bygger og deployer i snapshot versioner af NSPs wildfly container.
...