{"id":19402868,"url":"https://github.com/cscfi/oiva-backend","last_synced_at":"2026-05-15T00:41:06.738Z","repository":{"id":15992633,"uuid":"79096462","full_name":"CSCfi/oiva-backend","owner":"CSCfi","description":"Oiva - Opetushallinnon ohjaus- ja säätelypalvelu","archived":false,"fork":false,"pushed_at":"2022-09-08T00:07:47.000Z","size":2353,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":19,"default_branch":"develop","last_synced_at":"2025-01-07T12:26:20.804Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CSCfi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-16T08:07:45.000Z","updated_at":"2021-05-12T07:40:15.000Z","dependencies_parsed_at":"2023-01-11T20:24:19.062Z","dependency_job_id":null,"html_url":"https://github.com/CSCfi/oiva-backend","commit_stats":null,"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CSCfi%2Foiva-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CSCfi%2Foiva-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CSCfi%2Foiva-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CSCfi%2Foiva-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CSCfi","download_url":"https://codeload.github.com/CSCfi/oiva-backend/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240577895,"owners_count":19823536,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T11:26:10.509Z","updated_at":"2026-05-15T00:41:06.682Z","avatar_url":"https://github.com/CSCfi.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"                ____  _\n               / __ \\(_)\n              | |  | |___   ____ _\n              | |  | | \\ \\ / / _` |\n              | |__| | |\\ V / (_| |\n     ____      \\____/|_| \\_/ \\__,_|      _\n    |  _ \\           | |                | |\n    | |_) | __ _  ___| | _____ _ __   __| |\n    |  _ \u003c / _` |/ __| |/ / _ \\ '_ \\ / _` |\n    | |_) | (_| | (__|   \u003c  __/ | | | (_| |\n    |____/ \\__,_|\\___|_|\\_\\___|_| |_|\\__,_|\n\n# Buildaus- ja kehitysympäristön asentaminen\n\nTervetuloa 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.\n\n- [Buildaus- ja kehitysympäristön asentaminen](#Buildaus--ja-kehitysymp%C3%A4rist%C3%B6n-asentaminen)\n  - [Pikaohje](#pikaohje)\n  - [Alkuvalmistelut](#Alkuvalmistelut)\n    - [1. Docker](#1-Docker)\n    - [2. Java](#2-Java)\n    - [3. Maven](#3-Maven)\n    - [4. PrinceXML](#4-PrinceXML)\n    - [5. IDE](#5-IDE)\n    - [6. Projektin kääntäminen](#6-Projektin-k%C3%A4%C3%A4nt%C3%A4minen)\n        - [6.1 Huomioita](#61-Huomioita)\n    - [7. Tietokanta](#7-Tietokanta)\n    - [8. Palveluiden käynnistäminen](#8-Palveluiden-k%C3%A4ynnist%C3%A4minen)\n        - [8.1 Docker-palvelut](#81-Docker-palvelut)\n        - [8.2 Sovelluspalvelin](#82-Sovelluspalvelin)\n        - [8.3 Huomioita](#83-Huomioita)\n- [Lisätietoa ja tarkempia kuvauksia](#lisätietoa-ja-tarkempia-kuvauksia)\n  - [Debuggaus](#debuggaus)\n  - [Apuskriptit](#apuskriptit)\n  - [Testien ajaminen](#testien-ajaminen)\n      - [Yksikkötestit](#yksikkötestit)\n      - [Integraatiotestit](#integraatiotestit)\n  - [Pebblen ja PrinceXML:n käyttö](#pebblen-ja-princexmln-käyttö)\n  - [Debug ja JRebel](#Debug-ja-JRebel)\n  - [Sananen konfiguraatiosta](#Sananen-konfiguraatiosta)\n  - [Paketointi serveriympäristöihin](#Paketointi-serveriymp%C3%A4rist%C3%B6ihin)\n  - [Serverillä manuaalinen backendin käynnistys stagingissa:](#Serverill%C3%A4-manuaalinen-backendin-k%C3%A4ynnistys-stagingissa)\n\n## Pikaohje\n\nOhjeet Oiva-palvelun käynnistykseen tilanteessa, jossa kaikki tarvittavat riippuvuuudet on asennettu ja tietokanta importattu jo aikaisemmin:\n* Docker-konttien käynnistys: `./oiva-docker.sh start`\n* Koodien kääntäminen: `mvn clean install`\n* Sovelluspalvelimen käynnistys: `./oiva-backend.sh -c`\n* Käyttöliittymäkoodit: oiva-frontend-repositoryn juuressa `npm install \u0026\u0026 npm start`\n\nOiva-palvelu vastaa osoitteesta https://localhost\n\n## Alkuvalmistelut\n\nAsenna koneellesi seuraavat asiat. Tarkemmat ohjeet on kerrottu alempana, numeroiduin otsikoin:\n* [Docker](https://www.docker.com/).\n* [Java 8](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).\n* [Maven](http://maven.apache.org/) (3.3.1 tai uudempi).\n* [PrinceXML](https://www.princexml.com/).\n* IDE, kuten [VS Code](https://code.visualstudio.com/) tai [IntelliJ](https://www.jetbrains.com/idea/).\n\nMikäli käytät VS Code:a, kannattaa siihen asentaa hyödyllisiä lisäosia, kuten seuraavat:\n* Markdown All in One.\n\n## 1. Docker\nAsenna [Docker](https://www.docker.com/get-started). 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.\n\nAsenna myös [docker-machine](https://docs.docker.com/machine/install-machine/). Sitä tarvitaan integraatiotestien ajoon.\n\n## 2. Java\nAsenna Java 8. Mikäli sinulla on jo ennestään jokin toinen Java-versio asennettuna ja käytät Mac:ia, voit hallinnoida versioasennuksia [Jenv](http://www.jenv.be/):llä.\n\n## 3. Maven\nAsenna Maven. Mavenin suhteen ei tarvitse tehdä mitään erikoisia temppuja. Riittää, että siitä on asennettuna tarpeeksi tuore versio esim. \u003e= 3.6\n\n## 4. PrinceXML\nAsenna PrinceXML. PrinceXML-kirjastoa käytetään PDF-tiedostojen generointiin. Projektissa on toistaiseksi käytössä versio [Prince 13.5](https://www.princexml.com/releases/13/), mutta tuoreemman version käyttämiselle ei liene esteitä.\n\nMikä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](#82-Sovelluspalvelin). Esim:\n```\nOIVA_JAVA_OPTS=\"-Dprince.exec.path=/usr/local/bin/prince\"\n```\n\n## 5. IDE\nIDE:n suhteen ei ole sen kummempia vaatimuksia. VS Code ja IntelliJ ovat hyväksi todettuja vaihtoehtoja.\n\n## 6. Projektin kääntäminen\nKun olet käynyt kaikki edellä listatut kohdat läpi ja asentanut tarvittavat asiat, voit kokeilla kääntää projektin koodin. Suorita seuraava komento projektin juurihakemistossa:\n```\nmvn clean install\n```\n\n## 6.1 Huomioita\n\n* Pakettiin mukaan tuleviin resursseihin voi vaikuttaa käyttämällä joko Maven-profiilia -P dev tai -P prod. Oletusasetus on -P dev.\n* Kun backendiin tehdään muutoksia, joudut todennäköisesti rakentamaan paketit uudestaan ja tyhjentämään Redisin\n````\nmvn clean install\ndocker exec oiva-backend_amos-redis_1 bash -c \"redis-cli FLUSHALL\"\n````\n\n## 7. Tietokanta\nProjektissa on käytössä [PostgreSQL](https://www.postgresql.org/)-tietokanta, joka pyörii Docker-kontissa, virtuaalikoneiden verkossa. Tietokantaa ei siis tarvitse asentaa omalle koneelle.\nTietokannan ajantasaisuudesta vastaa [Flyway](https://flywaydb.org/)-migraatiotyökalu. Sinun ei tarvitse asentaa työkalua.\n\nManuaalisia tietokantaoperaatioita varten on olemassa `oiva-db.sh`-skripti. Sen avulla on mahdollista tehdä mm. tietokannan palautus ja [jOOQ](https://www.jooq.org/)-entiteettien luonti.\n\nPalautusta varten Docker-kontit pitää olla ajossa. Näiden käynnistäminen on ohjeistettu kohdassa [8.1](#81-Docker-palvelut). Lisäksi oiva-deplyment-repository pitää olla kloonattuna oiva-backend-hakemiston rinnalla. Tämä yksityinen repository sisältää oivan todellisen lupadatan.\n\nTietokannan luonti tai resetointi Oivalle:\n```\n$ ./oiva-db.sh create\n```\n\nJos 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.\n```\n$ ./oiva-db.sh amos generate\n```\n\n## 8. Palvelun käynnistäminen\n\nPalvelu voidaan käynnistää docker-palveluna tai lokaalina sovelluspalvelimena (suositeltu kehityskäyttöön).\n\n### 8.1 Docker-palvelu\n\nKäynnistä docker:\n\n    $ ./oiva-docker.sh start\n    \nProjektin 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.\n    \nDocker-compose luo 3 palvelua: amos-postgres, amos-redis ja nginx.\n\n### 8.2 Sovelluspalvelin\n\nKonfiguraatioihin 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.\n\nSyötä tiedostoon testi-opintopolun tarvitsemat käyttäjätunnus ja salasana. Nämä tiedot voi kysyä muilta kehittäjiltä.\n \n    OIVA_JAVA_OPTS=\"-Dopintopolku.username='käyttäjätunnus' -Dopintopolku.password='salasana'\"\n    \nBackend-palvelun käynnistäminen kehityskäyttöön:\n\n    $ ./oiva-backend.sh -c\n\nBackendin lisäksi yleensä tarvitaan frontendin käynnistys. Se tapahtuu oiva-frontend repositoryn juuressa:\n\n    $ npm install \u0026\u0026 npm start\n\nTämän jälkeen Oivaa voi käyttää osoitteessa https://localhost\n\n**Huom**\n\nHttps-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.\n\n### 8.3 Huomioita\n\nOivan backend-sovellus käynnistyy porttiin 8099 ja vastaa swagger-rajapintadokumentaatiolla osoitteesta http://localhost:8099.\n\nDockerin avulla käynnistettyä nginx-palvelinta käytetään reverse proxyna kehitysympäristössä. Sen avulla ohjataan https-liikenne oikeisiin kohdeosoitteisiin seuraavasti:\n\nOivan ohjaukset\n\n|Selaimen osoite|Kohde|\n|-----------------|---------------------|\n|https://localhost|http://localhost:3000|\n|https://localhost/api|http://localhost:8099|\n\n\n# Lisätietoa ja tarkempia kuvauksia\n\n## Debuggaus\n\nSovelluksen voi ajaa debug-moodissa lisäämällä d-parametrin käynnistyskomentoon, esim: \n\n`./oiva-backend.sh amos -c -d`\n\nYhteys otetaan Javan remote debuggerilla porttiin 5005.\n\n## Apuskriptit\n\nMuun muassa sovelluksen käynnistykseen ja testien ajoon liittyen on olemassa .sh-loppuisia skriptejä. Skriptien lyhyet infot saa näkyviin ajamalla skriptejä parametrilla `--help`. \n\n## Testien ajaminen\n\nYksikkötesteihin käytetään ScalaTest-kirjastoa ja Springin tarjoamia apuvälineitä. Yksikkö- ja integraatiotestit erotellaan\ntiedostopäätteellä. Yksikkötestit ovat muotoa \\*Test, esim: *MinunHienoTest*, ja integraatiotestit ovat muotoa \\*IT, esim:\n*MinunHienoIntegroivaIT*.\n\n### Yksikkötestit\n\nAja yksikkötestit: \n    \n    $ mvn test -DskipJavaUnitTests=false\n\nToistaiseksi muut kuin scalan yksikkötestit on asetettu oletuksena ohitettavaksi CI-ympäristön konfiguraatioista johtuen.  \n\n### Integraatiotestit\n\nEsiehtona integraatiotestien ajamiseen on docker-machinen asennus. Docker-machinen sisällä ajetaan redis-välimuistia ja postgresql-tietokantaa, joten niitä ei tarvitse itse käynnistää.\n\nAja integraatiotestit:\n    \n    $ ./run-integration-tests.sh\n\n- 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.\n- Yksittäisen luokan testien ajaminen on mahdollista esim. `--tests '*MuutospyyntoControllerIT'`. Kaikki MuutospyyntoControllerIT-loppuisten luokkien testit ajetaan.\n- Jos halutaan ajaa yksittäinen testi, niin loppuun pitää lisätä testifunktion nimi risuaidalla eroteltuna, esim. saveWithoutLogin-funktion ajaminen `--tests '*MuutospyyntoControllerIT#saveWithoutLogin'`\n\nMikä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`.\nVirtuaaliympäristön pystytys kestää hieman aikaa, joten samaa ympäristöä kierrätetään eri testiajojen välillä.\n\n## Pebblen ja PrinceXML:n käyttö\n\nPrinceXML tuottaa PDF-tiedostoja HTML-lähteistä jotka on muodostettu [Pebble-frameworkillä](http://www.mitchellbosecke.com/pebble).\n- Pebblen templatet ja resurssit on määritetty omassa git-respositoryssaan (oiva-template). Hanki templatet koneelle jolla ajat backendiä\n\nPebblen käyttämät template-tiedostot määräytyvät kolmen polun mukaisesti: juuripolku, versiopolku ja templaattitiedosto. \n- juuripolku (base path) on ``/opt/oiva/backend/``\n- versiopolku on ``template/default/``\n- templaattitiedosto on ``hakemus/hakemustemplate_fi.html``\n\nPebble-templateihin viitataan absoluuttisilla tai suhteellisilla poluilla.\n\nEsimerkki dev-profiililla luettavasta konfiguraatiosta (application-dev.yml) ja **juuripolusta**\n```\ntemplates:\n  base.path: ../../oiva-template\n```\n\n**Versiopolku** voidaan valinnaisesti määrittää hakukierros-kohtaisesti tietokannassa (ks. alla)\n\nJoissain 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\nko. kenttä on tyhjä niin sovellus käyttää oletustemplateja (template/default/).\n\nKäytettävä **templaattitiedosto** määräytyy templaattitiedostojen välisten kutsujen perusteella.\n\nKokeile tuottaa PDF-tiedosto seuraavan rajapinnan kautta: http://localhost:8099/pdf/esikatsele/{uuid}, jossa {uuid} on luvan uuid.\n\n## Debug ja JRebel\n\nRemote debug ja JRebel voidaan enabloida Spring Boot Maven pluginin konfiguraatiossa kohdassa``\u003cjvmArguments\u003e``. \nBlokkiin voidaan syöttää arvo komentokehotteelta ympäristömuuttujalla ``jvm.fork.arguments``.\n\nEsimerkki (yhdelle riville):\n\n    $ mvn spring-boot:run -Djvm.fork.arguments='-Djava.rmi.server.hostname=localhost -Xdebug \n    -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005\n    -Dproject.path=/path/to/oiva/backend -noverify \n    -agentpath:/patg/to/jrebel6/lib/libjrebel64.dylib'\n    \n    \n**HUOM:** ``\u003cjvmArguments\u003e``-blokki forkkaa uuden JVM-prosessin Spring bootille.\n\n## Sananen konfiguraatiosta\n\nKonfiguraatiot otetaan käyttöön seuraavassa järjestyksessä:\n\n1. Suorat komentoriviargumentit Mavenille (esim: ``-Dredis.host=myredishost.com``)\n2. Profiilispesifiset konfiguraatiot jar-paketin ulkopuolella (ei käytössä toistaiseksi)\n3. Profiilispesifiset konfiguraatiot (``\u003cproject-root\u003e/src/main/resources/config/application-{profile}.yml``)\n4. Yleiskonfiguraatio jar-paketin ulkopuolella (kehittäessä ``\u003cproject-root\u003e/application.yml`, tai jar-paketin ulkopuolella palvelimella)\n5. Yleiskonfiguraatio jar-paketissa (``\u003cproject-root\u003e/src/main/resources/config/application.yml``)\n\nKonfiguraatiotiedostojen Maven-filtteröintiä (e.g. ${placeholder}:ien korvausta) voi käyttää jar-paketin sisällä \noleville konfiguraatioille.        \n    \n## Paketointi serveriympäristöihin\n\nVoit rakentaa paketit ajamalla:\n\nmvn package -P dev  ( tai prof profiililla )\n\nJos käytät samalla paketin ulkopuolista konfiguraatiota. Mikäli haluat konffit paketin sisään, anna ne mukaan paketoinnissa.\n\nPaketit rakennetaan oikeilla tietokanta-IP:illä, postgressin salasanalla ja Mavenin profiililla \n(yleensä -Pprod, tekee prodiin ja stagingiin sopivan paketin):\n\n    $ mvn -Doiva.dbhost=oivatestdb.csc.fi -Dredis.host=127.0.0.1 -Doiva.dbpassword=\u003cINSERT REAL PASSWORD HERE\u003e -Pprod package # build prod package\n   \nTällöin asetukset ovat hardkoodattuina paketin sisällä, eikä ulkoista konfiguraatiota tarvita.   \n   \n   \n## Serverillä manuaalinen backendin käynnistys stagingissa:\n\n    $ java -jar oiva-backend.jar --spring.profiles.active=staging --server.port=8080\n    \n   Manuaalinen konffiesimerkki:\n    \n    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\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcscfi%2Foiva-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcscfi%2Foiva-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcscfi%2Foiva-backend/lists"}