____ _
/ __ \(_)
| | | |___ ____ _
| | | | \ \ / / _` |
| |__| | |\ V / (_| |
____ \____/|_| \_/ \__,_| _
| _ \ | | | |
| |_) | __ _ ___| | _____ _ __ __| |
| _ < / _` |/ __| |/ / _ \ '_ \ / _` |
| |_) | (_| | (__| < __/ | | | (_| |
|____/ \__,_|\___|_|\_\___|_| |_|\__,_|
Tervetuloa Oiva-projektin pariin! Näiden ohjeiden myötä sinun on mahdollista saada projekti nopeastikin käyntiin. Älä kuitenkaan lannistu, jos koet vastoinkäymisiä asennuksia tehdessäsi. Toisinaan paras apu on kipakka kehittäjille suunnattu kysymys. Vastauksen saatuasi voit täydentää ohjeiden puutteita.
Ohjeet Oiva-palvelun käynnistykseen tilanteessa, jossa kaikki tarvittavat riippuvuuudet on asennettu ja tietokanta importattu jo aikaisemmin:
- Docker-konttien käynnistys:
./oiva-docker.sh start - Koodien kääntäminen:
mvn clean install - Sovelluspalvelimen käynnistys:
./oiva-backend.sh -c - Käyttöliittymäkoodit: oiva-frontend-repositoryn juuressa
npm install && npm start
Oiva-palvelu vastaa osoitteesta https://localhost
Asenna koneellesi seuraavat asiat. Tarkemmat ohjeet on kerrottu alempana, numeroiduin otsikoin:
Mikäli käytät VS Code:a, kannattaa siihen asentaa hyödyllisiä lisäosia, kuten seuraavat:
- Markdown All in One.
Asenna Docker. Dockeria käytetään virtuaalikoneiden verkon luontiin. Verkon myötä kehittäjillä on käytössään yhtenevä kehitysympäristö. Tässä vaiheessa riittää, että saat Dockerin asennettua. Sen käyttöön palataan näissä ohjeissa myöhemmin.
Asenna myös docker-machine. Sitä tarvitaan integraatiotestien ajoon.
Asenna Java 8. Mikäli sinulla on jo ennestään jokin toinen Java-versio asennettuna ja käytät Mac:ia, voit hallinnoida versioasennuksia Jenv:llä.
Asenna Maven. Mavenin suhteen ei tarvitse tehdä mitään erikoisia temppuja. Riittää, että siitä on asennettuna tarpeeksi tuore versio esim. >= 3.6
Asenna PrinceXML. PrinceXML-kirjastoa käytetään PDF-tiedostojen generointiin. Projektissa on toistaiseksi käytössä versio Prince 13.5, mutta tuoreemman version käyttämiselle ei liene esteitä.
Mikäli et tee asennusta hakemistoon /usr/bin/prince, voit määrittää ohjelman sijainnin käynnistysparametreilla vars-username.sh-tiedostoon. Tarkempi kuvaus vars-tiedostosta on kohdassa 8.2 Sovelluspalvelin. Esim:
OIVA_JAVA_OPTS="-Dprince.exec.path=/usr/local/bin/prince"
IDE:n suhteen ei ole sen kummempia vaatimuksia. VS Code ja IntelliJ ovat hyväksi todettuja vaihtoehtoja.
Kun olet käynyt kaikki edellä listatut kohdat läpi ja asentanut tarvittavat asiat, voit kokeilla kääntää projektin koodin. Suorita seuraava komento projektin juurihakemistossa:
mvn clean install
- Pakettiin mukaan tuleviin resursseihin voi vaikuttaa käyttämällä joko Maven-profiilia -P dev tai -P prod. Oletusasetus on -P dev.
- Kun backendiin tehdään muutoksia, joudut todennäköisesti rakentamaan paketit uudestaan ja tyhjentämään Redisin
mvn clean install
docker exec oiva-backend_amos-redis_1 bash -c "redis-cli FLUSHALL"
Projektissa on käytössä PostgreSQL-tietokanta, joka pyörii Docker-kontissa, virtuaalikoneiden verkossa. Tietokantaa ei siis tarvitse asentaa omalle koneelle. Tietokannan ajantasaisuudesta vastaa Flyway-migraatiotyökalu. Sinun ei tarvitse asentaa työkalua.
Manuaalisia tietokantaoperaatioita varten on olemassa oiva-db.sh-skripti. Sen avulla on mahdollista tehdä mm. tietokannan palautus ja jOOQ-entiteettien luonti.
Palautusta varten Docker-kontit pitää olla ajossa. Näiden käynnistäminen on ohjeistettu kohdassa 8.1. Lisäksi oiva-deplyment-repository pitää olla kloonattuna oiva-backend-hakemiston rinnalla. Tämä yksityinen repository sisältää oivan todellisen lupadatan.
Tietokannan luonti tai resetointi Oivalle:
$ ./oiva-db.sh create
Jos tietokantatauluihin tulee muutoksia, JOOQ-luokat pitää generoida uudelleen. Uudelleengeneroinnissa käännetään oiva-core-model-moduuli, joka sisältää tietokantarakenteeseen vaikuttavat tietokantamigraatiot. Migraatiot ajetaan tietokantaa vasten, jonka sen hetkisen rakenteen perusteella muodostetaan DAO- ja entiteettiluokat java-koodina.
$ ./oiva-db.sh amos generate
Palvelu voidaan käynnistää docker-palveluna tai lokaalina sovelluspalvelimena (suositeltu kehityskäyttöön).
Käynnistä docker:
$ ./oiva-docker.sh start
Projektin juurihakemistossa sijaitsevaan oiva-docker.sh-tiedostoon on sisäänleivottu komento, jota usein käytetään käynnistämään Docker-kontit. Tyypillistä docker-compose up -komentoa ei siis tarvitse tässä projektissa käsin ajaa.
Docker-compose luo 3 palvelua: amos-postgres, amos-redis ja nginx.
Konfiguraatioihin pitää lisätä kehittäjäkohtaiset JVM-argumentit backend-palvelulle. Luo vars-KÄYTTÄJÄNIMESI.sh tiedosto, esimerkiksi vars-aheikkinen.sh. Käyttäjänimen saa selville ajamalla terminaalissa komennon whoami. Tiedosto voi sisältää bash-muuttujia jotka ladataan automaattisesti mukaan kun oiva-backend.sh suoritetaan.
Syötä tiedostoon testi-opintopolun tarvitsemat käyttäjätunnus ja salasana. Nämä tiedot voi kysyä muilta kehittäjiltä.
OIVA_JAVA_OPTS="-Dopintopolku.username='käyttäjätunnus' -Dopintopolku.password='salasana'"
Backend-palvelun käynnistäminen kehityskäyttöön:
$ ./oiva-backend.sh -c
Backendin lisäksi yleensä tarvitaan frontendin käynnistys. Se tapahtuu oiva-frontend repositoryn juuressa:
$ npm install && npm start
Tämän jälkeen Oivaa voi käyttää osoitteessa https://localhost
Huom
Https-liikenne edellyttää sertifikaattia. Kehitysympäristössä eli localhost-osoitteissa käytetään self signed -sertifikaattia, jota ei ole varmennettu luotettavasti. Selain varoittaa invalidista sertifikaatista, mutta varoituksen voi ohittaa.
Oivan backend-sovellus käynnistyy porttiin 8099 ja vastaa swagger-rajapintadokumentaatiolla osoitteesta http://localhost:8099.
Dockerin avulla käynnistettyä nginx-palvelinta käytetään reverse proxyna kehitysympäristössä. Sen avulla ohjataan https-liikenne oikeisiin kohdeosoitteisiin seuraavasti:
Oivan ohjaukset
| Selaimen osoite | Kohde |
|---|---|
| https://localhost | http://localhost:3000 |
| https://localhost/api | http://localhost:8099 |
Sovelluksen voi ajaa debug-moodissa lisäämällä d-parametrin käynnistyskomentoon, esim:
./oiva-backend.sh amos -c -d
Yhteys otetaan Javan remote debuggerilla porttiin 5005.
Muun muassa sovelluksen käynnistykseen ja testien ajoon liittyen on olemassa .sh-loppuisia skriptejä. Skriptien lyhyet infot saa näkyviin ajamalla skriptejä parametrilla --help.
Yksikkötesteihin käytetään ScalaTest-kirjastoa ja Springin tarjoamia apuvälineitä. Yksikkö- ja integraatiotestit erotellaan tiedostopäätteellä. Yksikkötestit ovat muotoa *Test, esim: MinunHienoTest, ja integraatiotestit ovat muotoa *IT, esim: MinunHienoIntegroivaIT.
Aja yksikkötestit:
$ mvn test -DskipJavaUnitTests=false
Toistaiseksi muut kuin scalan yksikkötestit on asetettu oletuksena ohitettavaksi CI-ympäristön konfiguraatioista johtuen.
Esiehtona integraatiotestien ajamiseen on docker-machinen asennus. Docker-machinen sisällä ajetaan redis-välimuistia ja postgresql-tietokantaa, joten niitä ei tarvitse itse käynnistää.
Aja integraatiotestit:
$ ./run-integration-tests.sh
- Testit on mahdollista ajaa debug-moodissa käyttämällä parametria
--debug, jolloin testiajo jää odottamaan debuggerin yhdistämistä ennen varsinaisten testien ajoa. Remote debuggerin portti on oletuksena 5005. - Yksittäisen luokan testien ajaminen on mahdollista esim.
--tests '*MuutospyyntoControllerIT'. Kaikki MuutospyyntoControllerIT-loppuisten luokkien testit ajetaan. - Jos halutaan ajaa yksittäinen testi, niin loppuun pitää lisätä testifunktion nimi risuaidalla eroteltuna, esim. saveWithoutLogin-funktion ajaminen
--tests '*MuutospyyntoControllerIT#saveWithoutLogin'
Mikäli testien ajo päätyy porttivirheeseen, esim. Bind for 0.0.0.0:15432 failed: port is already allocated, niin helpoimmalla pääsee poistamalla docker-machinen luoman virtuaalikoneen komennolla docker-machine rm test-db-machine.
Virtuaaliympäristön pystytys kestää hieman aikaa, joten samaa ympäristöä kierrätetään eri testiajojen välillä.
PrinceXML tuottaa PDF-tiedostoja HTML-lähteistä jotka on muodostettu Pebble-frameworkillä.
- Pebblen templatet ja resurssit on määritetty omassa git-respositoryssaan (oiva-template). Hanki templatet koneelle jolla ajat backendiä
Pebblen käyttämät template-tiedostot määräytyvät kolmen polun mukaisesti: juuripolku, versiopolku ja templaattitiedosto.
- juuripolku (base path) on
/opt/oiva/backend/ - versiopolku on
template/default/ - templaattitiedosto on
hakemus/hakemustemplate_fi.html
Pebble-templateihin viitataan absoluuttisilla tai suhteellisilla poluilla.
Esimerkki dev-profiililla luettavasta konfiguraatiosta (application-dev.yml) ja juuripolusta
templates:
base.path: ../../oiva-template
Versiopolku voidaan valinnaisesti määrittää hakukierros-kohtaisesti tietokannassa (ks. alla)
Joissain tilanteissa oiva.esitysmalli tietokantatauluun on voitu määritetty omat templatepolut templatepath sarakeeseen (tämä on templaten versiopolku). Tämä ei ole pakollista, sillä mikäli
ko. kenttä on tyhjä niin sovellus käyttää oletustemplateja (template/default/).
Käytettävä templaattitiedosto määräytyy templaattitiedostojen välisten kutsujen perusteella.
Kokeile tuottaa PDF-tiedosto seuraavan rajapinnan kautta: http://localhost:8099/pdf/esikatsele/{uuid}, jossa {uuid} on luvan uuid.
Remote debug ja JRebel voidaan enabloida Spring Boot Maven pluginin konfiguraatiossa kohdassa<jvmArguments>.
Blokkiin voidaan syöttää arvo komentokehotteelta ympäristömuuttujalla jvm.fork.arguments.
Esimerkki (yhdelle riville):
$ mvn spring-boot:run -Djvm.fork.arguments='-Djava.rmi.server.hostname=localhost -Xdebug
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005
-Dproject.path=/path/to/oiva/backend -noverify
-agentpath:/patg/to/jrebel6/lib/libjrebel64.dylib'
HUOM: <jvmArguments>-blokki forkkaa uuden JVM-prosessin Spring bootille.
Konfiguraatiot otetaan käyttöön seuraavassa järjestyksessä:
- Suorat komentoriviargumentit Mavenille (esim:
-Dredis.host=myredishost.com) - Profiilispesifiset konfiguraatiot jar-paketin ulkopuolella (ei käytössä toistaiseksi)
- Profiilispesifiset konfiguraatiot (
<project-root>/src/main/resources/config/application-{profile}.yml) - Yleiskonfiguraatio jar-paketin ulkopuolella (kehittäessä ``/application.yml`, tai jar-paketin ulkopuolella palvelimella)
- Yleiskonfiguraatio jar-paketissa (
<project-root>/src/main/resources/config/application.yml)
Konfiguraatiotiedostojen Maven-filtteröintiä (e.g. ${placeholder}:ien korvausta) voi käyttää jar-paketin sisällä oleville konfiguraatioille.
Voit rakentaa paketit ajamalla:
mvn package -P dev ( tai prof profiililla )
Jos käytät samalla paketin ulkopuolista konfiguraatiota. Mikäli haluat konffit paketin sisään, anna ne mukaan paketoinnissa.
Paketit rakennetaan oikeilla tietokanta-IP:illä, postgressin salasanalla ja Mavenin profiililla (yleensä -Pprod, tekee prodiin ja stagingiin sopivan paketin):
$ mvn -Doiva.dbhost=oivatestdb.csc.fi -Dredis.host=127.0.0.1 -Doiva.dbpassword=<INSERT REAL PASSWORD HERE> -Pprod package # build prod package
Tällöin asetukset ovat hardkoodattuina paketin sisällä, eikä ulkoista konfiguraatiota tarvita.
$ java -jar oiva-backend.jar --spring.profiles.active=staging --server.port=8080
Manuaalinen konffiesimerkki:
java -jar oiva-backend.jar --server.port=8080 --oiva.dbhost=192.168.1.165 --oiva.dbpassword=oiva --redis.host=192.168.1.199 --spring.profiles.active=prod