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-admin-web, nap-lobby-web og nap-test-web, bliver ./src folderen og konfigurationsfiler fra compose/configuration "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.

nap-admin-web

Indeholder et angular projekt, der har til formål at vise og håndtere alle tilgængelig projekter.

Projektet bruger standard strukturen for et Angular projekt, dvs. alt koden ligger inde i src/ mappen.

Nap-admin-web gør brug af nap-administration backenden, til at vise projekterne. 

Funktionalitet

Projektet har to faner, hhv "Projekter" og "Hjælp".

Projekter viser alle projekter. 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. 

Hjælp giver 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.

Applikationen kan derefter bruges på http://localhost:8080/nap/admin/web/, hvis nap-compose reverse proxy er opsat som beskrevet i 1.3.1 - Udvikling , ellers på http://Localhost:4500.

nap-admin-web bruger nap-administration som backend til at vise projekterne. nap-administration skal derfor startes som beskrevet i 5 - 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.

Der kan laves snapshots og release-candidates fra jenkins.

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-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 to faner, hhv "Projekter" 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. 

Hjælp beskriver hvad applikation omhandler, 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.

Applikationen kan nu nåes  http://localhost:8080/nap/lobby/web/, hvis nap-compose reverse proxy er opsat som i 1.3.1 - Udvikling, ellers på http://localhost:4200.

nap-lobby-web bruger nap-administration som backend til at vise projekterne. nap-administration skal derfor startes som beskrevet i 5 - 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.

Der kan laves snapshots og release-candidates fra jenkins.

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.

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, ellers på http://Localhost:4500.

CI

Jenkins filen beskriver jenkins pipelinen.

Der kan laves snapshots og release-candidates fra jenkins.

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 2 REST services for projekter og webapplikationer og håndterer de enkelte vært-/ LPSsystemers projektrettigheder. 

Udviklingsmiljø

Installer afhængigheder

Installer dependencies ved at "mvn install". 

Udviklingserver

For at starte en wildfly server til udvikling 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/, og  http://localhost:8080/nap/admin/services/main,  hvis nap-compose reverse proxy er opsat som i 1.3.1 - Udvikling.

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.

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.reference.facade.

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-admin-compose-ds.xml

<datasources xmlns="http://www.jboss.org/ironjacamar/schema"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.jboss.org/ironjacamar/schema https://docs.jboss.org/ironjacamar/schema/ironjacamar_1_0.xsd">
    <datasource jndi-name="java:jboss/datasources/admin" pool-name="MariaDBDS">
        <connection-url>jdbc:mysql://napadmindb:3306/administration?autoReconnect=true</connection-url>
        <driver>mysql</driver>
        <pool>
            <max-pool-size>30</max-pool-size>
            <min-pool-size>5</min-pool-size>
        </pool>
        <security>
            <user-name>root</user-name>
            <password>pw</password>
        </security>
        <validation>
            <check-valid-connection-sql>select 1</check-valid-connection-sql>
            <validate-on-match>false</validate-on-match>
            <background-validation>true</background-validation>
            <background-validation-millis>10000</background-validation-millis>
        </validation>
        <timeout>
            <idle-timeout-minutes>10</idle-timeout-minutes>
        </timeout>
    </datasource>
</datasources>

# Path to the service provider certificate
keystorePath=nap.jks

# Password to the service provider certificate
keystorePassword=Test1234

#  Path where public certificates of trusted STS services are stored
trustedStsCert=trusted-sts-certs.jks

# Password for the trusted sts certifikate keystore
trustedStsCertPassword=Test1234


# The audience, SAML-tokens are required to have
expectedAudience=https://audience.nspop.dk/nap

# Max clock skew
allowedClockDrift=3

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

Ved konfigurationsændringer skal wildfly serveren genstartes.

Persistence

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

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
    <persistence-unit name="NapAdminPersistence" transaction-type="RESOURCE_LOCAL">
        <non-jta-data-source>java:jboss/datasources/admin</non-jta-data-source>
        <class>dk.sds.nsp.nap.admin.entities.ProjectQuery</class>
        <class>dk.sds.nsp.nap.admin.entities.Project</class>
        <class>dk.sds.nsp.nap.admin.entities.WebApp</class>
        <class>dk.sds.nsp.nap.admin.entities.Manifest</class>
        <properties>
            <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect" />
            <property name="hibernate.hbm2ddl.auto" value="validate" />
            <property name="hibernate.connection.provider_disables_autocommit" value="true"/>
            <property name="hibernate.connection.release_mode" value="after_transaction" />
            <property name="hibernate.transaction.auto_close_session" value="true" />
            <property name="hibernate.current_session_context_class" value="thread" />
        </properties>
    </persistence-unit>
</persistence>

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.

# Localhost properties
localhost_stsEndpoint=http://test1.ekstern-test.nspop.dk:8080/sts/services/NewSecurityTokenService
localhost_idCardToSAMLAssertionEndpoint=http://test1.ekstern-test.nspop.dk:8080/sts/services/Sosi2OIOSaml
localhost_napLobbyUrl=http://localhost:8080/nap/lobby/web/
localhost_napWebUrl=http://localhost:8080/nap/lobby/web/services/main

#Test 1 properties
test1_stsEndpoint=http://test1.ekstern-test.nspop.dk:8080/sts/services/NewSecurityTokenService
test1_idCardToSAMLAssertionEndpoint=http://test1.ekstern-test.nspop.dk:8080/sts/services/Sosi2OIOSaml
test1_napLobbyUrl=TBA
test1_napWebUrl=TBA

#Test 2 properties
test2_stsEndpoint=http://test2.ekstern-test.nspop.dk:8080/sts/services/NewSecurityTokenService
test2_idCardToSAMLAssertionEndpoint=http://test2.ekstern-test.nspop.dk:8080/sts/services/Sosi2OIOSaml
test2_napLobbyUrl=TBA
test2_napWebUrl=TBA