Indeksoi Elasticsearchiin koulutustarjonnan dataa, jotta sitä voidaan jakaa tehokkaasti eri palveluille, erityisesti konfo-ui:lle (beta.opintopolku.fi) ja sen koulutushaulle.
Kouta-indeksoija on clojurella toteutettu ring/compojure/compojure-api web API. Indeksoija kuuntelee kouta-backendin lähettämiä sqs-viestejä ja viestin saatuaan hakee viestissä olleella id:llä entiteetin tiedot kouta-backendin rajapinnasta ja indeksoi tiedot Elasticsearchiin. Pyörittää myös cron jobia joka tarkastaa kouta-backendin muuttuneet tiedot siinä tapauksessa että jokin tieto on jäänyt indeksoimatta.
Kouta-indeksoijaan integroituvia oph:n palveluja on mm. konfo-backend, kouta-internal, kouta-external.
Indeksoijan käyttämät tietolähteet:
| Tietolähde | Haettavat tiedot |
|---|---|
| eperusteet | Ammatillisten koulutusten eperusteet sekä osaamisalojen ja tutkinnon osien kuvaukset |
| koodisto | Konfo-ui:ssa tarvittavien koodistojen koodien lokalisaatiot. Lisäksi tarvittavat koodirelaatiot ja niidenkin lokalisaatiot. |
| kouta-backend | Koulutukset, koulutusten toteutukset, hakukohteet, haut, valintaperustekuvaukset ja SORA-kuvaukset |
| lokalisaatio | Konfo-ui:ssa käyttäjille näytettävät tekstit kolmella eri kielellä (suomi, ruotsi ja englanti) |
| organisaatio | Koulutustoimijoiden, oppilaitosten ja toimipisteiden perustiedot ja niiden organisaatiohierarkia |
Asenna haluamallasi tavalla koneellesi
- Leiningen (Valitse asennus haluammallasi package managerilla)
- Docker (Elasticsearchia ja localstackia varten)
- AWS cli (SQS-jonoja varten)
- IntelliJ IDEA + Cursive plugin tai haluamasi kehitystökalu
Lisäksi tarvitset Java SDK:n (Unix pohjaisissa käyttöjärjestelmissä auttaa esim. SDKMAN!). Katso .travis.yml mitä versioita sovellus käyttää. Kirjoitushetkellä käytössä openJDK11.
Jos käytät IDEA:aa ja koodissa näkyy paljon virheitä, right clickaa project.clj-tiedostoa ja valitse 'Add as Leiningen Project'
Indeksoijan saa konfiguroitua luomalla tiedoston dev_resources/config.edn (laitettu .gitignoreen) ja asettamalla sinne
tarvittavat arvot. Tiedostosta dev_resources/config.edn.template näkee mitä arvoja sovellus tarvitsee toimiakseen.
Kirjoitushetken esimerkki konfigista, joka toimii untuva-testiympäristöä vasten lokaalilla Elasticsearchilla:
{:elastic-url "http://localhost:9200"
:cas {:username "kouta"
:password "tähän cas:n salasana"}
:hosts {:kouta-backend "https://virkailija.untuvaopintopolku.fi"
:kouta-external "https://virkailija.untuvaopintopolku.fi"
:virkailija-internal "https://virkailija.untuvaopintopolku.fi"
:cas "https://virkailija.untuvaopintopolku.fi"
:ataru-hakija ""}
:queue {:priority {:name "koutaIndeksoijaPriority" :health-threshold 10}
:fast {:name "koutaIndeksoijaFast" :health-threshold 10}
:slow {:name "koutaIndeksoijaSlow" :health-threshold 10}
:dlq {:name "koutaIndeksoijaDlq" :health-threshold 10}
:notifications {:name "koutaIndeksoijaNotifications" :health-threshold 10}
:notifications-dlq {:name "koutaIndeksoijaNotificationsDlq" :health-threshold 10}}
:sqs-region ""
:sqs-endpoint "http://localhost:4566"
:lokalisaatio-indexing-cron-string "* 0/30 * ? * *"
:organisaatio-indexing-cron-string "* 0 0 ? * *"
:queueing-cron-string "*/15 * * ? * *"
:notifier-targets ""
:kouta-indeksoija-kouta-cache-time-seconds 3600
:kouta-indeksoija-kouta-cache-size 1000
:kouta-indeksoija-organisaatio-cache-time-millis 1800000}Testiympäristöä voi vaihtaa laittamalla yllä olevasta configista untuva sanojen paikalle toisen testiympäristön nimen.
Cas-salasanan saa kaivettua untuvan ympäristökohtaisesta reposta opintopolku.yml tiedostosta kohdasta kouta_indeksoija_cas_password
Jos et tiedä mitä tämä tarkoittaa, kysy neuvoa kehitystiimiltä tai OPH:n ylläpidolta.
Testit ajetaan Kaocha test runnerilla.
Kaikki testit saa ajettua komentoriviltä komennolla lein test.
Yksittäisen testitiedoston saa ajettua lisäämällä ^:focus-tagin testitiedoston namespace-määrittelyn alkuun, esim.
ns ^:focus kouta-indeksoija-service.indexer.kouta-indexer-test.
Yksittäisen testin saa ajettua lisäämällä ^:focus-tagi ennen ajettavan testin nimeä, esim.
deftest ^:focus index-oppilaitos-test.
Testejä voi ajaa myös watch-modessa komennolla lein test --watch eli test runner ajaa testit automaattisesti uudestaan, kun koodia tai testejä muutetaan.
Testit käynnistävät Elasticsearchin docker-kontissa satunnaiseen vapaaseen porttiin. Watch-moodissa elasticsearch käynnistetään vain kerran, kun testiajo käynnistetään, ja se pysyy taustalla käynnissä kunnes testiajo lopetetaan. (Poikkeuksena muutamat mm. indeksien luomiseen liittyvät testit, jotka vaativat elasticin uudelleenkäynnistyksen testin alussa.)
Ennen indeksoijan ajamista lokaalisti täytyy pyörimässä olla
- Elasticsearch
- localstackin sqs-jonot
Elasticsearchia voi pyörittää docker-kontissa siten että data tallennetaan levylle vaikka kontin sammuttaisi. Tämä onnnistuu ajamalla ensin (ainoastataan ensimmäisellä kerralla):
docker volume create kouta-elastic-dataelasticsearch-koutan lataaminen vaatii kirjautumista ecr:n
aws ecr get-login-password --region eu-west-1 --profile oph-utility | docker login --username AWS --password-stdin 190073735177.dkr.ecr.eu-west-1.amazonaws.comJonka jälkeen kontin saa käyntiin komennolla:
docker run --rm --name kouta-elastic --env "discovery.type=single-node" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e xpack.security.enabled=false -v kouta-elastic-data:/usr/share/elasticsearch/data 190073735177.dkr.ecr.eu-west-1.amazonaws.com/utility/elasticsearch-kouta:8.15.0Jos tulee tarve poistaa data, komennolla docker volume --help saa apua volumeiden hallinnointiin.
Ilman volumea ajaminen onnistuu komennolla:
docker run --rm --name kouta-elastic --env "discovery.type=single-node" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e xpack.security.enabled=false 190073735177.dkr.ecr.eu-west-1.amazonaws.com/utility/elasticsearch-kouta:8.15.0Tässä tapauksessa tiedot häviävät kun kontin sammuttaa.
HUOM! Tämä tarvitsee tehdä vain jos konttiin tehdään muutoksia
elastic/build.sh
elastic/deploy.sh
Indeksoija vaatii lokaalin SQS-palvelun porttiin 4567. Sen voi käynnistää docker-konttiin ajamalla skriptin
tools/start_localstack ja pysäyttää skriptillä tools/stop_localstack.
tools/send_local skriptiä voi käyttää viestien lähetykseen lokaaleihin jonoihin, jos jostain syystä
sellainen tarve tulee.
Kun Elasticsearch ja sqs-jonot ovat pyörimässä indeksoijan saa käyntiin komennolla lein dev
Tämä avaa swaggerin selaimeen osoitteeseen http://localhost:8100/kouta-indeksoija/swagger/index.html
Suositeltava kehitysympäristö on IntelliJ IDEA + Cursive plugin mutta sovelluksen ja testien ajamisen kannalta nämä eivät ole välttämättömiä. Jos et tee paljon clojure-kehitystä, myöskään cursive ei ole välttämätön.
Testidataa saa omaan lokaaliin Elasticsearchiin laittamalla tiedoston dev_resources/config.edn arvot
:hosts {:kouta-backend "https://virkailija.untuvaopintopolku.fi"
:kouta-external "https://virkailija.untuvaopintopolku.fi"
:virkailija-internal "https://virkailija.untuvaopintopolku.fi"
:cas "https://virkailija.untuvaopintopolku.fi"osoittamaan haluamaasi testiympäristöä vasten ja ajamalla swaggerista POST /kouta-indeksoija/api/kouta/all.
Voit myös indeksoida vain yksittäisen entiteetin, esimerkiksi ajamalla swaggerista
POST /kouta-indeksoija/api/kouta/koulutus/:oid
Muiden palvelujen (kouta-internal, kouta-external, konfo-backend) testien käyttämän Elasticsearch mock-datadumpin generointi tapahtuu skripteillä, jotka löytyvät hakemistosta test/mocks.
palvelunnimi_mocks.clj -tiedostoissa on skripti kyseiselle palvelulle. Kun olet tehnyt tarvittavat muutokset testidatan generoivaan skriptiin, aja komento:
lein elasticdump:<palvelun nimi>
eli esimerkiksi:
lein elasticdump:konfo-backend
Se suorittaa skriptin ja luo elasticsearch-testidata-dumpin hakemistoon elasticdump/palvelunnimi
Korvaa sitten kyseisen palvelun repositoriossa elastic_dump -hakemiston sisältö tiedostot tuohon hakemistoon luoduilla tiedostoilla.
Testiympäristöjen swaggerit löytyvät seuraavista osoitteista:
Jotta pääset näihin käsiksi täytyy sinulla olla OPH:n ympäristöihin päästävä VPN:n päällä ja indeksoijan tunnus ja salasana tiedossa. Näihin apua saa kehitystiimiltä tai OPH:n ylläpidolta.
Asennus hoituu samoilla työkaluilla kuin muidenkin OPH:n palvelujen. Cloud-basen dokumentaatiosta ja ylläpidolta löytyy apuja.
Asennuksen yhteydessä tapahtuvaan mahdolliseen uudelleenindeksointiin löytyy ohjeet täältä: Katkoton indeksointi
Jos tekemäsi muutos koodiin muuttaa indeksoijan tallentaman, palvelusta ulos välitettävän datan muotoa, päivitä project.clj tiedostoon kouta-indeksoijan versionumeroa semanttisen versioinnin mukaisesti. Eli jos teet taaksepäinyhteensopivan muutoksen, esimerkiksi lisäät indeksiin uuden kentän, nosta minor versiota (6.2.0 -> 6.3.0). Jos taas teet muutoksen joka ei ole taaksepäinyhteensopiva, esimerkiksi poistat indeksistä kentän, nosta major versiota (6.2.0 -> 7.0.0).
Travis tekee buildin jokaisesta pushista ja siirtää luodut paketit opetushallituksen artifactoryyn.
Paketti luodaan aina master-haarasta. Mikäli tulee tarve sadaa paketointi kehityshaarasta, täytyy muuttaa
./.travis.yml -tiedostoa. Tällainen tilanne voi olla esimerkiksi jos tekee muutoksia kouta-indeksoijan tietomalliin
eikä vielä halua mergetä muutoksia masteriin, mutta tarvitsisi uutta tietomallia kuitenkin esimerkiksi
kouta-internalin, kouta-externalin tai konfo-backendin kehityshaaroissa.
Tarvittava muutos travis.yml tiedostoon on tällainen:
(myös tiedoston git historiasta voi katsoa mallia)
...
- provider: script
script: lein deploy
skip_cleanup: true
on:
branch: <branchin-nimi>
...
Mikäli haluaa uuden version paketin vain lokaalia kehitystä varten, saa sen luotua komennolla lein install, joka luo paketin
lokaaliin Maven repoon.
Indeksoijan lokit löytyvät AWS:n cloudwatchista log groupista <testiympäristön nimi>-app-kouta-indeksoija (esim. hahtuva-app-kouta-indeksoija). Lisäohjeita näihin ylläpidolta.
https://travis-ci.com/github/Opetushallitus/kouta-indeksoija
Jos törmäät seuraavaan virheeseen esimerkiksi testejä ajaessasi:
An error occurred (AccessDeniedException) when calling the GetAuthorizationToken operation: User: arn:aws:iam::123456789:user/[email protected] is not authorized to perform: ecr:GetAuthorizationToken on resource: * with an explicit deny in an identity-based policy
Aja seuraava loitsu (mahdollisesti joutuu myös ajamaan aws configure ennen tätä):
AWS CLI v1:
aws ecr get-login --no-include-email --region eu-west-1 --profile oph-utility
AWS CLI v2:
aws ecr get-login-password --region eu-west-1 --profile oph-utility | docker login --username AWS --password-stdin 190073735177.dkr.ecr.eu-west-1.amazonaws.com
ARM-arkkitehtuurilla elasticsearchin docker kontti buildattava itse.
elastic/create-bundles.sh
elastic/build.sh
Vanhan readme:n tiedot joiden paikkansapitävyyttä ei ole selvitetty:
During development it's easy to test what you have done by using a REPL. This works best with IDEA and cursive (others also, but the instructions here apply for Cursive).
Create a REPL run configuration. When you import the project one should be created for you. If this is not the case, right click project.clj and select run. Then edit the configuration:
- Name it something like Dev REPL
- Add a JVM argument
-Dtest=false - When you start the repl type
(go)to activate mount.core (brings settings to namespaces).
Create another repl configuration, e.g. Test repl and add JVM argument -Dtest=true.
To run tests every time code is changed:
(use 'midje.repl)(no need to use(go)here)(autotest)
The application can notify others when information is indexed. This is controlled with :notifier-targets
value in dev_resources/config.edn. It should be defaulted to "", ie. no changes will be sent.
When wanting to validate locally that the notifications are working, one of the easiest way is with dummy-web-server.py in tools:
- Run
python2 tools/dummy-web-server.py 9900to start it in port 9900. - Change
:notifier-targetsindev_resources/config.ednto"http://localhost:9900" - You can edit the script to set the return code and headers.
The script will log every access to console.
If you need to nuke ElasticSearch analyze settings, there are two tools that can be used test different settings and see how they affect queries and word analysis.
test/misc/analyze_settings_test_tool.clj can be used if you want to test how different analyze settings affect queries.
It mimics both nested structure in kouta-indeksoija search indexes and search queries generated by konfo-backend for koulutus
and oppilaitos searches.
test/misc/analyzers_test_tool.clj can be used to test how different search analyze settings handle different words and phraises.
Both tools have main method and they can be run for example in Idea by choosing run command when clicking right mouse button.
Make sure you have test profile enabled in Leiningen Projects/Profiles.
App config is handled with Mount, cprops and in (mostly dev) cases with environment variables. To add a conf parameter to the application, add it to dev_resources/config.edn (for development) AND oph-configuration/config.edn.template. In order for the template file to work in non-local environments, the variable must also be added to the variable file in [email protected]:environment-{ophitest|ophp|ophprod|vagrant}.git in deploy/_vars.yml.
NOTE: The cron-string variable roughly follows cron scheduler syntax with a few alterations shown here.
Copyright (c) 2017 The Finnish National Board of Education - Opetushallitus
For details see LICENSE.txt