EXAM asennusohjeet v1.2

EXAM asennusohjeet v1.2 Järjestelmäriippuvuudet Tietokanta Apache & Shibboleth Exam-applikaatio Examin asetukset Tietokantayhteys Käyttäjäroolien määritys Hostname Sähköpostiasetukset Opintohallintajärjestelmän URL Opintojaksohaun tiedot Järjestelmän alustusdata Liitteiden ja raporttien hakemistot Tenttien oletuskestot Oletusaikavyöhyke Examin kännistys Käynnistys palveluna Pääkäyttäjien lisääminen Logitiedot Järjestelmän päivittäminen Pääsy Examin lähdekoodirepositorioon avataan pyynnöstä. Pyynnöt vastaanottaa kristiina.uolia (at)csc.fi. Exam pyörii Play-sovelluspalvelimen päällä ja ulkopuolisen HTTP-palvelimen takana. Autentikointi on ulkoistettu shibboleth-toteutukselle, josta vastaavat eri HAKA-organisaatiot. Järjestelmäriippuvuudet Riippuen käyttöjärjestelmästä, aseta aikavyöhykkeeksi UTC ja käytössä olevan lokaalin oletusenkoodaukseksi UTF-8. Jotta ne asetetaan palvelimen käynnistyessä, tulee ne asettaa profiilitiedostossa, RHEL 6 -palvelimella esimerkiksi näin. $ sudo vi /etc/environment -> kirjoita TZ=UTC LC_ALL=en_US.UTF-8 Asenna Oraclen Java versio 1.7 tai 1.8, esim: $ wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" http://download.oracle.com/otn-pub/java/jdk/8u40-b26/jdk-8u40-linux-x64.rpm $ sudo rpm -ivh jdk-8u40-linux-x64.rpm # korkiako: Tai suoraan $ sudo yum install jdk1.8.0_40 Asenna koneelle ruby ja siihen sass gem, esimerkiksi: $ sudo yum install ruby rubygems $ sudo gem install sass Lataa, pura ja halutessasi lisää myös PATH:iin Play Frameworkin versio 2.2.2 osoitteesta http://downloads.typesafe.com/play/2.2.2/play-2.2.2.zip, esim:

$ wget http://downloads.typesafe.com/play/2.2.2/play-2.2.2.zip $ sudo unzip play-2.2.2.zip -d /opt $ export PATH=$PATH:/opt/play-2.2.2 Asenna Apache HTTP-palvelin, versio 2.2.15 tai uudempi, esim: $ sudo yum install httpd $ sudo chkconfig --levels 235 httpd on... Asenna postgresql, versio 8.4.20 tai uudempi (ks. esim https://wiki.postgresql.org/wiki/yum_installation). $ sudo vi etc/yum/pluginconf.d/rhnplugin.conf -> lisää osion 'main' alle: exclude=postgresql* $ sudo yum localinstall http://yum.postgresql.org/9.4/redhat/rhel-6-x86_64/pgdg-redhat94-9.4-1.noarch.rpm $ sudo yum install postgresql94-server $ sudo chkconfig postgresql-9.4 on $ sudo service postgresql-9.4 initdb Muokkaa postgresql-serverin autentikointiasetuksia. Ilmeisesti Play ei saa yhteyttä tietokantaan oletuksena olevaa ident-tunnistautumismetodia käytettäessä, joten on suositeltavaa vaihtaa IP:n yli tapahtuvien yhteyksien autentikointimetodiksi md5. Lokaalisti voi luottaa yhteyden olevan autentikoitu, jos haluaa. $ sudo -u postgres vi /var/lib/pgsql/9.4/data/pg_hba.conf -> muokkaa tiedoston lopussa olevia asetuksia vaikka näin # TYPE DATABASE USER ADDRESS METHOD # "local" is for Unix domain socket connections only local all all trust # IPv4 local connections: host all all 127.0.0.1/32 md5 # IPv6 local connections: host all all ::1/128 md5 Varmista, että tietokantapalvelimen aikavyöhyke on UTC: $ sudo -u postgres vi /var/lib/pgsql/9.4/data/postgresql.conf -> muokkaa kohdat timezone ja log_timezone tämän näköisiksi timezone = 'UTC' log_timezone = 'UTC' Käynnistä tietokantapalvelin: $ sudo service postgresql-9.4 start Asenna Git, esim:

$ sudo yum install git Tietokanta Luo palvelimelle tietokanta sitnet ja käyttäjä haluamillasi tunnuksilla, esimerkiksi: $ sudo -u postgres createuser -SPRD sitnet $ sudo -u postgres createdb --owner=sitnet sitnet Jos kaikki on mennyt oikein, seuraavan kirjautumisen pitäisi onnistua: $ psql -Usitnet sitnet psql (9.4.1) Type "help" for help. sitnet=> Poistu psql-konsolista komennolla \q Jos haluat importata tietokannan dumpista: $ sudo -u postgres psql sitnet < /tmp/sitnet-dump.psql Jos haluat ajaa integraatiotestejä tarvitset lisäksi testitietokannan: $ sudo -u postgres createdb --owner=sitnet sitnet_test Apache & Shibboleth Lisää reverse proxy Exam-järjestelmälle. Apachen tai valitun http-proxyn konfiguraatioon tulee myös organisaatiokohtaiset shibboleth-asetukset. Portti 9000 on Playn oletusportti. Esimerkki:

<VirtualHost 193.166.44.29:443> ProxyPreserveHost On ServerName https://sitnet01.csc.fi # no proxy for Shibboleth ProxyPass /Shibboleth.sso/! ProxyPass / http://127.0.0.1:9000/ ProxyPassReverse / http://127.0.0.1:9000/ # Shibboleth-kirjautumista varten koko asennus Shibboleth-suojauksen taakse <Location "/"> AuthType shibboleth ShibRequestSetting requiresession 1 # http headereita ei saisi käyttää, mutta tämä on nyt ainoa vaihtoehto ShibUseHeaders On # tämä olisi suositusten mukainen tapa välittää käyttäjäattribuutit, mutta Play Framework ei tue AJP-protokollaa, joka edellytyksenä # ShibUseEnvironment On require valid-user </Location> </VirtualHost> Examiin on toteutettu rajapinta opintosuoritusten hakua varten. Exam ei rajoita pääsyä tähän polkuun mitenkään, joten se tehdään apachen configuraatioissa. https://domainname.fi/integration/record/:startdate, ISO-8601-formaatissa. jossa päivämääräparametri (:startdate) tulee olla annettuna <Location /integration/record> Satisfy Any Allow from all </Location> Kun konfiguroit shibbolethia seuraavat attribuutit (attribute-map.xml) pitäisi headerien mukana saada Exam-järjestelmään asti: unscoped-affiliation eppn mail sn displayname Shib-Session-ID preferredlanguage schacpersonaluniquecode Attribuutit tulee olla URL-enkoodattuna:

shibboleth2.xml  <RequestMapper type="native"> <RequestMap applicationid="default" encoding="url">... Exam-applikaatio Lisää järjestelmään haluamallasi tavalla rajoitettu käyttäjä/rooli (tässä: sitnet/sitnet) $ sudo groupadd sitnet $ sudo useradd -s /sbin/nologin -g sitnet -d /opt/exam sitnet $ sudo passwd sitnet $ sudo chown -R sitnet.sitnet /opt/exam $ sudo chmod 755 /opt/exam Ota gitiä apuna käyttäen examin-lähdekoodi repositoriosta haluamaasi hakemistoon (tässä käytetään /opt/exam -hakemistoa) $ cd /opt/exam; sudo -u sitnet git clone https://username@source.csc.fi/scm/git/sitnet/sitnet Luo examin tarvitsemat hakemistot ja anna niille tarvittavat oikeudet, esimerkiksi: $ sudo -u sitnet mkdir -p /opt/exam/sitnet/data/reports $ sudo -u sitnet mkdir -p /opt/exam/sitnet/data/attachments/question $ sudo -u sitnet mkdir -p /opt/exam/sitnet/data/attachments/exam Anna lisäksi exam-käyttäjälle oikeudet ajaa Playtä: $ sudo chown -R sitnet.sitnet /opt/play-2.2.2 Examin asetukset

Asetuksia muokataan asetustiedostojen kautta. Tiedostot sijaitsevat hakemistossa conf. Yleisesti ottaen tuotantoasennuksen asetukset tulisi olla tiedostossa conf/production.conf ja kaikenlaiset testiasennukset tulisi olla konfiguroitavissa conf/application.conf -tiedostossa. Jos on tarvetta, voi tietysti määritellä myös täysin uusia asetustiedostoja. Tietokantayhteys Yhteysparametrit examin tietokantaan täytyy määrittää asetustiedostossa. Jos tietokanta on luotu tässä dokumentissa kuvatulla tavalla, näyttävät parametrit tältä: db.default.driver=org.postgresql.driver db.default.url="jdbc:postgresql://localhost/sitnet" db.default.user=sitnet db.default.password=sitnet Käyttäjäroolien määritys Katso conf/production.conf Exam tukee kolmea käyttäjäroolia: opettaja opiskelija pääkäyttäjä Käyttäjärooli asetetaan käyttäjälle kun hän kirjautuu järjestelmään ensimmäisen kerran HAKA:n kautta unscoped-affiliation attribuutin mukaan. Koska unscoped-affiliation attribuutin käyttö ei ole yhdenmukaista eri organisatioissa, Examin konfiguraatiossa voidaan määrätä mitä Examin roolia unscoped-affiliation arvot vastaavat. esimerkiksi: sitnet.roles.student="student" sitnet.roles.teacher="faculty,affiliate,alum" sitnet.roles.admin="staff" Unscoped-affiliation attribuutti voi sisältää myös useamman roolin puolipisteillä erotettuna. Tässä tapauksessa exam vertailee kutakin roolia omiin määrityksiinsä ja ensimmäisen osuman kohdalla asettaa käyttäjälle kyseisen roolin (eli jos vaikka unscoped-affiliation on "x;y;z" ja examin määrityksessä olisi vaikkapa sitnet.roles.teacher="a;b;z;", tulisi käyttäjärooliksi teacher eli opettaja. Shibboleth-autentikointiin pikakorjaus, jolla käytäjän oletusrooliksi tulee opiskelija, vaikka unscoped-affiliation -attribuutin arvo ei olisikaan sitä mitä Exam odottaa:

diff --git a/app/controllers/sessioncontroller.java b/app/controllers/sessioncontroller.java index 90222e1..598c028 100644 --- a/app/controllers/sessioncontroller.java +++ b/app/controllers/sessioncontroller.java @@ -166,7 +166,8 @@ public class SessionController extends SitnetController { List<String> affiliations = Arrays.asList(affiliation.split(";")); Map<String, List<String>> roles = getroles(); - String rolename = null; + //String rolename = null; + String rolename = "STUDENT"; if (!Collections.disjoint(affiliations, roles.get("student"))) { rolename = "STUDENT"; } else if (!Collections.disjoint(affiliations, roles.get("teacher"))) { Tämän jälkeen roolin vaihtaminen halutuksi suoraan kannasta sitnet_users_sitnet_role -taulussa (toimii, kunnes koodi korjataan niin, että roolivaihdokset tarkistetaan/tallennetaan jokaisen kirjautumisen yhteydessä). Hostname Järjestelmän hostname asetetaan sitnet.application.hostname muuttujaan. Muuttujaa käytetään mm. esim: ilmoittautumislinkin generointi linkit sähköpostiraporteissa sitnet.application.hostname="https://exam.oulu.fi" Sähköpostiasetukset Exam lähettää erilaisia muistutusviestejä ja raportteja sähköpostilla. Sähköpostiasetukset konfiguroidaan Playn production.conf tiedostossa smtp.host=smtp.yliopisto.fi smtp.port=587 smtp.ssl=true smtp.tls=true smtp.user="exam@yliopisto.fi" smtp.password="111111111" Opintohallintajärjestelmän URL Opintohallintajärjestelmän osoite asetetaan muuttujaan. Muuttujaa käytetään mm. sähköpostiviesteissä linkkien generointiin, esimerkiksi: sitnet.basesystemurl="https://weboodi.oulu.fi/oodi/" Opintojaksohaun tiedot Opintojaksoja voi hakea ulkopuolisesta järjestelmästä. Haun saa päälle asettamalla sitnet.integration.courseunitinfo.active=true. Haussa

käytettävä URL määritetään erikseen: # external course interface in use: true=on, false=off sitnet.integration.courseunitinfo.active=true sitnet.integration.courseunitinfo.url="http://winoodi.csc.fi:8180/kshj/resources/v1/ex am/courseinfo" Järjestelmän alustusdata Exam vaatii toimiakseen joitain pakollisia tietoja, joilla tietokanta alustetaan ensimmäisen käynnistyksen yhteydessä. Tuotantoasennuksen alustusdata löytyy conf/production-initial-data.yml -tiedostosta. production-initial-data.yml lada taan, jos asetuksissa on määritelty sitnet.production.initial.data="true", muussa tapauksessa tietokanta alustetaan ini tial-data.yml tiedostolla (kehitysvaiheen testidata). sitnet.production.initial.data="true" Liitteiden ja raporttien hakemistot Exam tallentaa tenttiin ja kysymyksiin liittyvät tiedostot sekä Excel-raportit tiedostojärjestelmään. Polut voidaan asettaa kofiguraatiotiestossa oleviin muuttujiin. Hakemistot luodaan oletuksena sitnet-hakemiston alle (/opt/exam/sitnet). # kysymysten liitetiedostot sitnet.question.attachments.path=data/attachments/question # tentin liitetiedostot sitnet.exam.attachments.path=data/attachments/exam # Excel raportit sitnet.reports.path=data/reports Tenttien oletuskestot Tenttien mahdolliset kestot minuuteissa määritellään asetuksissa: # exam durations available for choosing, in minutes sitnet.exam.durations="45,90,110,180" Oletusaikavyöhyke Käyttäjien oletusaikavyöhyke, jota käytetään ajan näyttämiseen sähköposteissa. Jos oletuksena on, että järjestelmän käyttäjät ovat pääasiassa Suomesta, kannattaa käyttää oletusarvoa: # application timezone, used for formatting timestamps in emails to users # For allowed values see: http://joda-time.sourceforge.net/timezones.html sitnet.application.timezone="europe/helsinki"

Examin kännistys Käynnistääksesi exam tuotantoasetuksilla siirry Examin juurihakemistoon (/opt/exam/sitnet) ja käynnistä Exam seuraavalla komennolla $ sudo -u sitnet play -Dconfig.resource=production.conf -DapplyEvolutions.default=true ja kirjoita konsolissa start, jolloin play, kääntää ja alkaa suorittaa koodia, ctrl+d jättäää prosessin tausta-ajoon, ctrl+c tappaa prosessin. Exam-järjestelmää voi testailla ilman shibbolethia, jos asetustiedostossa oleva sitnet.login="haka " on muutettu sitnet.login="debug". Tällöin käyttäjät ja käyttäjäroolit tulee olla lisättynä käsin examin-tietokantaan. Oletuksena Exam käynnistetään application.conf-tiedoston asetuksilla ellei vaihtoehtoista konfiguraatiotiedostoa erikseen määritetä - esimerkiksi allaoleva käynnistää Examin asetuksilla, jotka luetaan tiedostosta conf/demo.conf: $ sudo -u sitnet play -Dconfig.resource=demo.conf -DapplyEvolutions.default=true On huomioitava, että postgresql, apache ja shibd ovat käynnistetty ennen examin käynnistystä. Integraatiotestit voidaan ajaa play-konsolissa kommennolla test. Tällöin testitietokannan pitää olla luotuna (katso Tietokanta). Käynnistys palveluna Examin voi käynnistää myös palveluna. Tätä varten löytyy käynnistysskripti examin lähdekoodeissa /scripts/exam

exam #!/bin/bash # # exam # # chkconfig: 345 80 10 APP_PATH=/opt/exam/sitnet ACTIVATOR_PATH=/opt/play-2.2.2/play APP_OPTS="-Dconfig.resource=production.conf -DapplyEvolutions.default=true clean compile run" APP_USER=sitnet start() { echo -n "Starting EXAM" cd $APP_PATH sudo -u "$APP_USER" "$ACTIVATOR_PATH" $APP_OPTS } stop() { echo "Stopping EXAM" pkill -u $APP_USER } case "$1" in start) start ;; stop) stop ;; restart) stop start ;; esac Skriptin muuttujat tulee asettaa sen mukaan miten asennus on tehty. Riippuen käyttöjärjestelmästä käyttö tapahtuu jotenkin näin: $ sudo -i $ cp scripts/exam /etc/init.d $ chmod 755 /etc/init.d/exam $ chkconfig exam on $ service sitnet start (tämä on itseasiassa kätevämpi käynnistää tmux- tai screen-ikkunaan) Pääkäyttäjien lisääminen Jos ja kun pääkäyttäjän roolin omaavia käyttäjiä ei voda suoraan tuoda HAKA:sta, täytyy käyttäjäroolin korotus tehdä käsin. Käyttäjän, josta halutaan pääkäyttäjä, täytyy ensin kirjautua EXAMiin HAKA-roolissansa. Tämän jälkeen tietokannassa korotetaan roolia vaikkapa näin:

$ psql -Usitnet sitnet sitnet=> update sitnet_users_sitnet_role set sitnet_role_id = (select id from sitnet_role where name = 'ADMIN') sitnet-> where sitnet_users_id = (select id from sitnet_users where eppn = 'USER_EPPN'); UPDATE 1 sitnet=> \q Korvaa ylläoleva USER_EPPN kyseisen käyttäjän eppn-tunnisteella. Kun käyttäjä seuraavan kerran kirjautuu EXAMiin, kirjautuu hän pääkäyttäjän roolissa. Logitiedot EXAMin kirjoittaa logeja hakemistoon logs. Logituksen asetuksia voi muokata asetustiedostosta. Ohjeet tähän löytyvät Playn sivuilta: https://www. playframework.com/documentation/2.2.x/settingslogger Järjestelmän päivittäminen Kun järjestelmää päivitetään, on syytä ottaa huomioon ainakin seuraavat asiat. Ota varmuuskopiot ainakin seuraavista: hakemisto, joka sisältää kysymyksiin ja tentteihin liittyvät liitetiedostot käytettävä konfiguraatiotiedosto production.conf tietokantadumppi ennen päivitystä Varmuuden vuoksi ennen uudelleenkäynnistystä on hyvä poistaa asennushakemistosta kansiot /bin ja /target, jonne saattaa olla jäänyt tiedostoja, jotka aiheuttavat ongelmia päivitetyssä ympäristössä: $ sudo -u sitnet rm -rf bin target $ sudo -u sitnet play -Dconfig.resource=production.conf -DapplyEvolutions.default=true