TIM-palveludokumentaatio

Tämä dokumentaatio kuvaa TIM-järjestelmän arkkitehtuuria sovellus-, laitteisto- ja toimintatasolla. Dokumentoinnin tavoitteena on selkeyttää TIM-järjestelmän toimintaa koko palvelun näkökulmasta sekä tarjota pohjan jatkokehitystä varten.

Dokumentin sisältö perustuu vuoden 2021 TJTA1181-kurssilla tuotettuihin dokumentteihin.

TIM (The Interactive Material) on Jyväskylän yliopiston Informaatioteknologian tiedekunnan kehittämä materiaalien hallintajärjestelmä, joka perustuu vuorovaikutteiseen materiaalin tuottamiseen. Järjestelmässä on myös lukuisia oppimisenhallintaympäristöille ominaisia toiminnallisuuksia.

Jyväskylän yliopistolla järjestelmää käytetään erityisesti oppimismateriaalien tuotantoon ja kurssien hallintaan. Verrattuna Jyväskylän yliopistossa muihin käytettyihin ympäristöihin, kuten Optimaan, Moodleen tai Koppaan, TIM tarjoaa käyttäjilleen mahdollisuuden paljon monipuolisempaan ja yksityiskohtaisempaan kehittämiseen oppimisen polulla.

TIM-järjestelmää esitetään viidestä näkökulmasta:

• järjestelmäarkkitehtuuri, joka kattaa järjestelmäarkkitehtuurin rakenteen, ohjelmistot, toiminnallisuudet ja rajapinnat;
• laitearkkitehtuuri;
• tallennusratkaisut;
• monitorointi ja ylläpito sekä;
• palvelupyynnöt.

Dokumentaatio on pyritty kirjoittamaan yleiskäyttöiseksi kuvaukseksi TIM-järjestelmästä. Tästä huolimatta jotkin dokumentaatiossa olevat asiat koskevat juuri Jyväskylän yliopistossa käytettävää TIM-järjestelmän asennusta. Tästä syystä tässä dokumentissa

• TIM-järjestelmällä viitataan yleisesti kaikkiin TIM-järjestelmän asennuksiin, ja
• JYU TIM -instanssilla viitataan Jyväskylän yliopistolla käytettävään TIM-järjestelmän asennukseen.

JYU TIM -instanssin käytänteet voi käyttää esimerkkinä muiden TIM-järjestelmien asennusten ylläpitämiseksi.

1. Järjestelmäarkkitehtuuri

Järjestelmäarkkitehtuurin osalta TIM muodostaa kokonaisrakenteen, joka muodostuu Docker-konteissa ajettavista ohjelmista, palvelimista, järjestelmää pyörittävistä ohjelmista ja rajapinnoista. Alla oleva kuva esittää yksinkertaistettua TIM-järjestelmäarkkitehtuuria:

1.1 Kontit

TIM hyödyntää Docker-konttiteknologiaa, jossa TIM on rakenteeltaan jaettu erilaisiin kevyisiin virtuaalikoneisiin, eli kontteihin (container), joilla on omat rajapintansa. TIM-järjestelmän ohjelmat ovat pakattuna asennuspaketteihin (image), joista Docker luo automaattisesti ajettavat kontit. TIM-järjestelmä on jaettu useampaan konttiin parantaakseen ohjelmien välistä eristystä sekä helpottaakseen ylläpitoa.

TIM-järjestelmän kontit voi jakaa karkeasti viiteen tyyppiin:

• Pääkontti, eli TIM-kontti on se, jossa pyörii TIM-järjestelmän palvelintoteutus. Kontit keskustelevat TIM-kontin kanssa siten, että TIM lähettää konteille pyyntöjä halutusta toiminnasta. Pääosin kaikki kontit keskustelevat vain TIM-kontin kautta.

• Plugin-kontit, jotka sisältävät TIM-järjestelmään kirjoitettuihin materiaaleihin liitettävät liitännäiset. TIM tarjoaa palveluja eri liitännäisten käyttöön, kuten menetelmän, jolla rekisteröidä itsensä TIM:n käyttöön. Liitännäiset ovat riippuvaisia TIM:stä ja tarvitsevat toimiakseen isäntäsovellustaan. Näitä ovat esimerkiksi

  • stack: tarjoaa STACK-pluginin,
  • csplugin: tarjoaa csplugin-pluginin

• Ulkoiset kontit, joiden kautta voidaan tarjota lisäpalveluja käyttäjälle, esim. työkaluja matemaattiseen mallinnukseen tai visuaaliseen esittämiseen. Lisäksi muutama ulkoinen kontti tarjoaa pääkontille palveluja, kuten tietokantaa ja välimuistia. Liitännäiskonttien sisältämien ohjelmistopakettien kirjasto on erittäin laaja ja käytännössä lähes rajattomasti joustava ja laajennettavissa. Näitä ovat esimerkiksi:

  • postgreqsl, jossa pyörii PostgreSQL-tietokantaohjelmisto,
  • dumbo, joka tarjoaa Pandoc-dokumenttikääntäjän REST-rajapinnan yli

• Ajonaikaiset kontit, jotka muut kontit voivat luoda TIM-järjestelmän ajon aikana. Esimerkiksi csplugin-kontti luo uusia csplugin-kontteja aina, kun jotain ohjelmaa kontin kautta ajetaan, minkä jälkeen kontti katoaa.

• Testikontit, jotka käytetään vain automaattitestauksessa. Testikontit eivät ole päällä tuotannossa.

TIM-järjestelmän ajon aikana on käytössä 20, mutta ajonaikaiset kontit voivat hetkellisesti kasvattaa ajettavien konttien lukumäärää. Kaikkien vakiokonttien määrittelyt löytyvät TIM-järjestelmän docker-compose.tmpl.yml-tiedostosta:

tim-jyu/tim:cli/templates/docker/docker-compose.tmpl.yml

Kyseinen tiedosto on pohjatiedosto; sisällön perusteella luodaan varsinainen docker-compose.yml asentajan asetusten perusteella.

1.1.1 Tärkeimmät ulkopuoliset kontit

Alla on kuvattu joitain tärkeimmät ulkopuoliset kontit, jotka tarvitaan pääkontin toimintaa varten.

• caddy-kontti ottaa Caddy-ohjelmalla käyttäjän selaimesta tulevia HTTP-pyyntöjä vastaan ja välittää ne muille konteille. Kontti välittää suurimman osan pyynnöistä TIM-kontille, jossa pyörii gunicorn-palvelin, joka käsittelee niitä ja välittää TIM-järjestelmän palvelinpuolen koodille käsiteltäväksi.
• dumbo-kontti muuntaa TIM-järjestelmään kirjoitettujen materiaalien markdown-kielellä kirjoitetun tekstin HTML- tai PDF-muotoon.
• postgres-konttiin tallentuu lähes kaikki TIMin tiedot PostgreSQL-tietokantaan.
• redis-kontissa ajetaan KeyDB-välimuistipalvelin, johon TIM-kontti tallentaa väliaikaista tietoa, kuten materiaalien esikäännetyt HTML-tiedostot. KeyDB on puolestaan Redis-välimuistipalvelimen forkki, joka parantaa tietojen varastointi- ja kyselynopeutta moniajoympäristöissä. TIMissa käytetään monin pakoin termiä redis historiallisista syistä.

1.2 Ohjelmat

TIM-järjestelmä käyttää erilaisia ohjelmistoja konttien sisällä sekä niiden ulkopuolella. Dokumentaation kirjoitushetkellä TIM-järjestelmässä käytettävät ohjelmat ovat esitetty alla olevassa taulukossa.

Taulukossa on käytössä suodatus- ja hakuominaisuus.

Ohjelmalistauksessa versionumero on suuntaa antava ja ollut käytössä dokumentin tekohetkellä. Ohjelmien tämänhetkiset versiot voi katsoa Docker-konttien asennuspakettien konfigurointitiedostoista:

• TIM: TIM-imagen Dockerfile
  
• csPlugin: csPlugin-imagen Dockerfile
  
• STACK: STACK-imagen Dockerfile
  
• Haskell-plugins: haskellplugins-imagen Dockerfile

1.3 Rajapinnat

Rajapinnat mahdollistavat integraation ohjelmistoon ja sen avulla voidaan tehdä pyyntöjä ohjelmistolle, josta halutaan noutaa tai tuoda tietoja. TIM-järjestelmässä käytetään erilaisia rajapintoja sekä konttien väliseen että ulkopuolisten järjestelmien ja TIM-järjestelmän väliseen keskusteluun.

TIM-järjestelmän sisäistä viestinvaihtoa kutsutaan sisäisiksi rajapinnoiksi. Sisäiset rajapinnat käytetään konttien väliseen tietojen välittämiseen suljetun Docker-virtuaaliverkon yli. Puolestaan TIM:in ulkoisilla rajapinnoilla liitytään ulkopuolella oleviin palveluihin, joita ilman TIM voi toimia ja jotka toimivat itse ilman TIM:iä. Toisin kuin sisäisillä rajapinnoilla, keskustelu ulkoisilla rajapinnoilla on varmennettu salaisella avaimella tai IP-lukolla.

1.3.1 Sisäiset rajapinnat

REST-rajapintaa käytetään pääsääntöisesti konttien väliseen tiedonvaihtoon. REST (Representational State Transfer) on HTTP-protokollaan perustuva arkkitehtuurimalli ohjelmointirajapintojen toteuttamiseen. REST-rajapintaa käytetään ensisijaisesti pluginien ja TIM-kontin väliseen tiedonvälitykseen. Tarkka TIM-kontin ja pluginien välinen protokolla on dokumentoitu Plugin-speksissä.

RESP-protokolla toimii TIM-palvelimen ja Redis-palvelimen rajapinnassa. RESP on eräänlainen serialisointiprotokolla, joka tukee seuraavia tietotyyppejä: yksinkertaisia merkkijonoja (Simple Strings), virheitä (Errors), kokonaislukuja (Integers), bulkkijonoja (Bulk Strings) ja taulukoita (Arrays).

SQL-protokolla, joka on myös kyselykieli, toimii TIM-palvelimen ja PostgreSQL-tietokannanhallintajärjestelmän rajapinnassa. SQL:n avulla yhdistytään tietokantaan ja sillä toteutetaan tietokantakyselyt ja erilaiset muutokset tietokantaan.

Celery-protokolla toimii Redis-palvelimen ja Celery-palvelimen rajapinnassa. Celery on Python-pohjainen tehtäväjono-ohjelmistopaketti ja Redis toimii eräänlaisena välimuistina. Redis-palvelin tallentaa viestit, jotka ovat kotoisin ohjelmakoodista ja niissä kuvataan, että työ tulee laittaa Celeryn tehtäväjonoon. Redis toimii myös Celeryn tehtäväjonosta tulevien tulosten varastointina, jotka sitten jonon kuluttajat noutavat. Celery-protokolla toimii tässä siis viestinvälittäjänä ja se on kirjoitettu Pythonilla, mutta protokolla voidaan toteuttaa millä tahansa kielellä.

1.3.2 Ulkoiset rajapinnat

REST/HTML-selainrajapinnan avulla käyttäjän selain keskustelee TIM-palvelinkontin kanssa. Tämä rajapinta on tarkoitettu vain käyttöliittymälle erilaisiin toiminnallisuuksiin, kuten lohkojen lisäämiseen ja editointiin ja kommenttien lisäämiseen. Melkein jokainen käyttöliittymän vuorovaikuttava toiminnallisuus tekee jossain kohtaa REST-rajapinnan kutsun palvelimeen.

SMTP on TCP-pohjainen protokolla, jota käytetään viestien välittämiseen eri sähköpostipalvelimien kesken ja sen käyttöön on varattu portti numero 25. TIMin käytössä oleva ulkopuolinen SMTP-palvelin on yliopiston oma. SMTP on siis oikeasti protokolla, mutta se voidaan nähdä rajapintana. Rajapinta on siis se, kun SMTP-palvelin mahdollistaa sähköpostin lähetyksen.

Sisun SCIM-rajapintaa (System for Cross-domain Identity Management) käytetään kurssien ryhmätietojen synkronointiin Sisun kanssa. SCIM-rajapinta keskustelee REST-rajapinnan kautta eli se käyttää puhtaita HTTP-kutsuja.

Sisun REST-rajapintaa käytetään mm. arvosanojen kirjaamiseen, johon ei siis käytetä SCIM-rajapintaa.

Hakan SAML-rajapinta (Security Assertion Markup Language) tekee mahdolliseksi käyttäjien kirjaamisen TIMiin yliopistotunnuksella. SAML on tietojärjestelmien käyttäjien valtuuttamiseen ja tunnistamiseen liittyvien tietojen jakamiseen tietoverkossa keskittyvä standardi. Teknisesti katsottuna SAML on XML-standardi ja siihen liittyy tietyt rajapinnat, jotka Haka ja TIM tarjoavat. Nämäkin on toteutettu käytännössä REST-rajapintana.

OAuth2-rajapinta on käytössä käyttäjien tunnistamiseen ulkoisissa järjestelmissä TIMin avulla. OAuth2 on laajassa käytössä oleva protokolla ja rajapinta, jonka avulla käyttäjä voi antaa ulkoisille järjestelmille lupaa vuorovaikuttaa tunnistautumista vaativien resurssien kanssa. TIM tarjoaa seuraavat resurssit ulkopuolisille järjestelmille rajapinnan kautta:

• Käyttäjän käyttäjätunnus
• Käyttäjän sähköpostiosoitteet
• Käyttäjän koko nimi

Tällä hetkellä nämä tiedot voidaan käyttää käyttäjän sisäänkirjaamiseen ulkoisiin järjestelmiin.

JSON/CSV -rajapintaa voidaan käyttää erilaisen määrämuotoisen tiedon hakemiseen tai syöttämiseen TIM:iin. JSON on yksinkertainen avoimen standardin tiedostomuoto, jolla välitetään ja tallennetaan tietoa. Se perustuu JavaScriptiin, mutta on siitä riippumaton. JSON on kieli, muttei ohjelmointikieli. JSON:ia käytetään, kun dataa lähetetään palvelimelta verkkosivulle. CSV taas on yksinkertainen tiedostomuoto, jota käytetään taulukkotietojen, kuten laskentataulukon tai tietokannan, tallentamiseen. CSV-muodossa olevat tiedostot voidaan tuoda ja viedä ohjelmiin, jotka tallentavat tietoja taulukoihin, kuten Microsoft Excel tai OpenOffice Calc. CSV lyhenne tulee siitä, että se tarkoittaa “pilkuilla erotettuja arvoja”.

2. Laitearkkitehtuuri

TIM-järjestelmää voi ajaa monipuolisilla palvelimilla. Yleiset järjestelmävaatimukset tuotantokäytölle ovat:

• Docker 19.03 tai uudempi
  • Kernelin ja tiedostojärjestelmän tuettava Dockerin overlay2-ajuria (xfs:n tapauksessa oltava d_type=true)
• Levy: SSD, min. 16 GB
  • Suositus: min. 0,5 TB
• RAM: min 2 GB + min. 2 GB jokaista 100 aktiivista samanaikaista käyttäjää (esim. koe, liveluento) kohden
  • Jos käyttö ei ole samanaikaista, voi pärjätä pienemmällä
  • Suositus: min. 8 GB + 4 GB jokaista 100 aktiivista samanaikaista käyttäjää kohti
• CPU: min. 8 ydintä
• Internet-linkki: min. 1 Gbps

Jyväskylän yliopistossa käytettävä laitteisto ja arkkitehtuuri on kuvattu erillisessä dokumentissa: Jyväskylän yliopiston TIM-asennuksen arkkitehtuuri.

3. Tallennusratkaisut

TIM-järjestelmän tietokantapalvelut hoitaa PostgreSQL-palvelin, joka ajetaan omassa Docker-kontissa. Puolestaan TIM-järjestelmään kirjoitettavat dokumentit, niiden muokkaushistoria sekä liitetiedostot tallennetaan normaaleina Linux-tiedostoina.

JYU TIM -instanssissa ovat lisäksi käytössä häiriönhallinta- ja varmuuskopiointipalvelut, joilla varmistetaan järjestelmän toimivuutta.

3.1 Tallennus

3.1.1 Tietokanta

Suurin osa TIM-järjestelmän tiedoista tallennetaan PostgreSQL-relaatiotietokantaan. Nämä tiedot ovat esimerkiksi käyttäjät, käyttäjäryhmät, vastaukset tehtäviin, dokumenttien ja kansioiden metadata (nimi, sijainti, oikeustiedot) ja asetukset.

Relaatiotietokannan relaatiotaulut määritellään ohjelmallisesti pääkontin lähdekoodissa SQLAlchemy-kirjastolla. Kaikkien relaatioiden nimet ovat listattu tim_app.py -tiedostossa.

3.1.2 Dokumentit ja muokkaushistoria

Dokumentit ja muokkaushistoria tallennetaan tiedostoina suoraan tiedostojärjestelmään. Oletuksena nämä tiedostot tallennetaan kansioon timApp/tim_files.

Kaikki dokumentit koostuvat lohkoista, jotka ovat erilliset tiedostot. Lohkotiedostot sisältävät JSON-dataa, joilla on ainakin tunniste (id), raaka sisältö (md) ja tarkistusarvo (t). Jos lohkoa muokataan, tehdään täysin uusi tiedosto.

Dokumentit ovat taas tiedostoja, jossa luetellaan siihen kuuluvien lohkojen tunnisteet ja tarkistusarvot järjestyksessä. Jos dokumentissa kahden lohkon paikkaa vaihdetaan, tehdään täysin uusi tiedosto omalla versionumerolla. Dokumentin muokkaustapahtumat tallennetaan omaan changelog-tiedostoon. Vanhat tiedostot aina pysyvät, joten täysi historia on olemassa.

Dokumenttien sekä lohkojen kansio- ja tiedostorakenteet kuvataan tarkemmin omassa dokumentissa:

Johdatus TIMin kehitykseen – Dokumentit

3.1.3 Liitetiedostot

TIMissä liitetiedostot tallennetaan levylle normaaleina Linux-tiedostoina. Mikäli ne ovat suurempia tiedostoja, kuten tehtävien palautuksia PDF-muodossa, käytetään GhostScript-ohjelmaa pakkaamaan tiedostot pienemmiksi tilan säästämisen vuoksi.

Liitetiedostoista tallennetaan tietokantaan tieto, mistä tiedostopolusta liitetiedosto löytyy, sekä tiedot kaikista dokumenteista, joihin liitetiedosto on liitetty. Liitetiedostojen käyttöoikeuksia hallitaan tietokannan puolella.

3.2 Varmuuskopiointi

Oletuksena TIM-järjestelmä ei tee varmuuskopioita automaattisesti. Tätä varten kuitenkin on olemassa prosessia helpottavia skriptejä GitHub-projektissa. Alla kuvataan olennaiset varmuuskopioitavat tiedot, suositeltavat ohjelmat ja JYU TIM -instanssin varmuuskopiointikäytänteet esimerkinomaisesti.

Tietokannan varmuuskopiointi onnistuu tekemään PostgreSQL:n pgdump-ohjelmalla. Tätä varten TIM-järjestelmän lähdekoodissa on valmis postgre_backup.sh -skripti. JYU TIM -instanssissa tietokanta varmuuskopioidaan tunnin välein. Lisäksi viikkoa vanhat varmuuskopiot poistetaan JYU TIM -instanssilta postgre_backup_rotate.sh-skriptillä. Tämä tehdään tilan säästämiseksi, ja koska instanssilla ajetaan snapshot-varmuuskopiot.

Itse tiedostojärjestelmän varmuuskopiointi tehdään JYU TIM -instanssilla rsync ja scp -ohjelmilla. Varmuuskopiointi tehdään koko JYU TIM-instanssin pääkansiosta, johon sisältyy timApp/tim_files-kansio, sekä tietokannan varmuuskopiokansiosta. Nämä snapshotit tallennetaan 90 vuorokauden ajaksi JYU TIM -instanssin varmuuskopiointipalvelimelle, joka on kahdennettu.

3.2.1 Palautustavoitteet JYU TIM -instanssilla

JYU TIM -instanssilla

• RPO (Recovery Point Objective) kuvaa, kuinka pitkältä ajalta tietoa voidaan pahimmillaan menettää häiriön sattuessa. JYU TIMin tilasta tehdään varmuuskopio kerran päivässä. Varmuuskopiosta palautetaan siis enimmillään 24h päästä versio häiriön tapahduttua.

• RTO (Recovery Time Objective) kuvaa, kuinka nopeasti järjestelmä voidaan palauttaa häiriötilanteesta. JYU TIM -instanssilla tämä aika on täysin riippuvainen työvoiman saatavuudesta, varsinkin työajan ulkopuolella. Jos sitä ei pystytä välttämättömien tapauksien (esim. pääsykokeiden) takia tekemään välittömästi, se on noin 15 min. Ajan myötä tavoitteena on laskea tämä aika noin minuuttiin järjestelmän kahdennuksen myötä.

4. Monitorointi ja ylläpito

TIM-järjestelmän monitorointi ja ylläpito on osittain automatisoitua. Näille toiminnoille ei ole yhtä keskitettyä käyttöliittymää, vaan ne tehdään pääosin suorittamalla kometoja TIM-palvelimella. TIM-järjestelmän testaaminen tehdään sekä automaatiotestauksella että toiminnallisella testauksella käyttäjien puolesta.

JYU TIM-instanssilla ylläpitäjät huolehtivat palvelinten monitoroinnista. Palvelinten prosessorien kuormitustasoja seurataan satunnaisilla tarkistuksilla. Palvelimille ei ole määritelty päivittäisiä tai kuukausittaisia huoltotoimenpiteitä joiden yhteydessä niiden kunnot tarkistettaisiin. Mahdollisiin ongelmiin puututaan niitä havaittaessa, esimerkiksi järjestelmän toimintahäiriöiden yhteydessä.

4.1 Monitorointityökalut

4.1.1 Lokitiedot

TIM-järjestelmän eri Docker-kontit keräävät omia lokeja. Docker-konttien lokit voi lukea komennolla

./dc logs -t -f kontin_nimi

missä kontin_nimi on tarkasteltavan kontin nimi. Nämä lokit voi tarkastella ja analysoida muilla ohjelmilla, esimerkiksi grep-hakuohjelmalla.

TIM-järjestelmän jotkin kontit tallentavat lokinsa suoraan tiedostoihin tarkempaa analysointia varten. Nämä lokit tallennetaan tim_logs-kansioon, jonka sijainti on säädettävissä (esim. JYU TIM -instanssilla se on /extra/tim_logs). Nämä lokit ovat

• pääkontin loki (timLog.log), joka tallentaa pääkontille tulleet HTTP-kutstut, sekä palvelimen erilaiset tapahtumat, varoitukset ja virheet. Loki toimii tapahtumalokina, sillä kutsujen yhteydessä näkee käyttäjätunnukset, IP-osoitteet, sekä kutsun keston. Lokit voi analysoida grep tai glogg-ohjelmilla.
• caddy-kontin lokit (caddy-kansio), joka tallentaa kaikki TIM-instanssin ulkopuolelta tulevaa liikennettä. Lokit voi analysoida goaccess-ohjelmalla.

4.1.2 Uptime-monitorointi

TIM-järjestelmän tilaa seurataan healthcheck.sh-skriptillä. Skripti lähettää minuutin välein HTTPS-pyynnön TIM-palvelimelle tarkistaakseen, onko tämä pystyssä. Jos TIM-palvelin ei vastaa pyyntöön, lähettää skripti automaattisesti sähköpostin TIM-järjestelmän ylläpitäjille.

Pyynnöt tehdään kerran minuutissa, mikäli palvelin vastaa. Joka kerta, kun palvelin ei vastaa pyyntöön, pidennetään aikaväliä minuutilla.

JYU TIM -instanssilla skripti ajetaan toisella yliopiston sisällä olevalla palvelimella.

4.1.3 “wuff”-virheilmoitukset

Mikäli TIM-järjestelmän pääkontin palvelinkoodi tuottaa poikkeuksen (eli TIM-ohjelmisto palauttaa tilan, johon ei olla varauduttu), järjestelmä tuottaa tästä virheen.

Näistä virheistä lähetetään virheilmoitukset (“wuffit”) TIM-järjestelmään konfiguroituun sähköpostiosoitteeseen. Ilmoitukseen sisältyy muun muassa

• käyttäjä ja HTTP-pyyntö, joka aiheutti virheen;
• kooditiedosto, jossa virhe ilmeni;
• virheilmoitus.

4.1.4 Kuormituksen tarkistus

Järjestelmän kuormitusta seurataan tarpeen vaatiessa. Kuormituksesta ei aiheudu automaattisia hälytyksiä palvelun ylläpitäjille. Mikäli käyttäjiltä tulee raporttia tai muista lokeista huomataan poikkeamaa, seurataan järjestelmän kuormitusta.

Kuormituksen visualisoinnissa käytetään top-ohjelmaa, jolla nähdään resurssien käyttöaste ja prosessit, jotka näitä resursseja kuluttavat.

4.2 Päivitykset ja huoltokatkot

Järjestelmän päivityksiä tehdään ketterästi. Päivityksiä julkaistaan niiden valmistuttua, jopa useamman kerran saman vuorokauden aikana parhaimmillaan.

TIM-järjestelmä ei hyödynnä tarkkaa versiointistandardia, kuten Semveriä. Versiointi perustuu pääsääntöisesti TIM-JYU/TIM -projektiin tehtyyn viimeisimmän muutoksen hash-arvoon. Ennen kuin päivitykset viedään tuotantoon, muutoksille ajetaan automaattiset yksikkötestit. Lisäksi suurimmista muutoksista julkaistaan ensin väliaikainen esikatseluversio, jossa palvelua voidaan testata manuaalisesti.

Päivityksiä suorittaessa, täytyy joissain tapauksissa käynnistää järjestelmä tai sen osia uusiksi. Nämä huoltokatkot pyritään ajoittamaan JYU TIM -instanssilla kello 18 jälkeen, jotta käyttäjille koituisi mahdollisimman vähän häiriötä.

Huoltokatkoista tiedotetaan erikseen käyttäjille etukäteen asettamalla palveluun ilmoitus, jossa tiedotetaan tulevan huollon ajankohta ja arvioitu kesto.

Kurssinpitäjät ilmoittavat palvelun ylläpitäjille, mikäli palveluun on tulossa odotettavasti suurta kuormaa esimerkiksi tenttien vuoksi. Katkot ja päivitykset voidaan ajoittaa näiden tilanteiden ulkopuolelle.

4.3 Ylläpitotehtävät

Alla olevassa taulukossa ovat listattu olennaisimmat ylläpitotehtävät:

Muut uudelleenkäynnistystarpeet ja komennot ovat avattu tarkemmin Ylläpitäjien toiminnot -dokumentissa.

5. Palvelupyynnöt

Palvelupyyntökäytänteet koskevat käyttäjien pyyntöihin, kyselyihin, neuvontaan, käyttöoikeuksiin ja opastuksiin liittyvää toimintaa TIM-järjestelmän sisällä. Luvussa käsitellään pääosin JYU TIM -instanssin käytänteitä, mutta osa asioista koskevat yleistä TIM-järjestelmää.

5.1 Roolit ja vastuut

JYU TIM -instanssilla palvelupyyntöroolit jaetaan kahteen ryhmään: TIM-ylläpitäjät ja käyttäjät.

5.1.1 TIM-ylläpitäjät

TIM-ylläpitäjäryhmä koostuu joukosta asiantuntijoita. Palvelupyyntöihin kohdistuvat roolit ja vastuut ovat kaikkien ylläpitotiimin asiantuntijoiden vastuulla.

Tämä käsittää

• palvelupyyntöjen hallinnoinnin
• palvelupyyntöprosessin eri vaiheet
• yksittäisten pyyntöjen käsittelyn tai hylkäämisen
• pyynnön edistymisen ja ratkaisun seurannan
• kommunikoinnin pyynnön lähettäjän kanssa
• tarvittaessa asianomaisten henkilöiden tiedon ajantasaisuuden varmistaminen pyyntöjen edistymisestä

5.1.2 Käyttäjät

Palvelupyynnöt esitetään yksittäisten käyttäjien toimesta suorittamalla palvelupyyntö sille tarkoitetun kanavan välityksellä. Käyttäjä voi halutessaan osallistua keskusteluun, joka yleensä syntyy lähetetyn pyynnön yhteyteen. Käyttäjä voi mahdollisesti joutua tarjoamaan lisätietoja palvelupyynnön yhteydessä, jotta tämän täyttyminen voidaan varmistaa onnistuneesti.

Käyttäjät voidaan jakaa ryhmiin, mikä vaikuttaa oikeuksien hallintaan sekä palvelupyyntöjen luonteeseen. Valmiita ryhmiä TIMissä ovat muun muassa

• Haka users – HAKA-tunnistuksella kirjautuneet käyttäjät,
• Teachers – opettajat,
• Administrators – TIM-ylläpitäjät,
• Group admins – Käyttäjät, jolla on oikeus luoda uusia ryhmiä,
• Logged-in users – sisäänkirjautuneet henkilöt,
• kotiorganisaation käyttäjät – HAKA-tunnistuksella kirjautuneet käyttäjät, jotka kuuluvat konfiguroituun kotiorganisaatioon. JYU TIM -instanssilla tämä on jyu.fi
• Anonymous users – sisäänkirjautumattomat käyttäjät

Jos ongelmatilanteessa tai muuta tehtävää suoritettaessa käyttöoikeudet eivät riitä, on otettava yhteyttä TIM-järjestelmän ylläpitoon. Tällaiset tapaukset ovat esimerkiksi oman ryhmän luominen, jos käyttäjä ei ole Group admins -ryhmässä.

Käyttäjien palvelupyynnöt voivat riippua myös käyttäjän käyttöoikeuksista palvelupyynnön kohteena olevaan dokumenttiin tai kansioon.

Dokumentin tai kansion käyttöoikeudet voi nähdä ja muokata näiden kohteiden Manage-sivuilta. Mahdolliset käyttöoikeudet ovat listattu alla:

• View antaa oikeuden nähdä kohteen sisällön.

• Copy antaa katseluoikeuden lisäksi nähdä dokumenttien lähdetekstin sekä kopioida dokumenttien lohkot.

• Edit antaa kopiointioikeuden lisäksi oikeuden muokata dokumentin sisältöä.

• See answers antaa oikeuden tarkastella muiden vastauksia.

• Teacher käyttöoikeuksien avulla opettajat voivat opetukseensa esim. antaa opiskelijoille palautetta vastauksista.

• Manage antaa oikeuden muokata dokumentin oikeuksia, paitsi korkeimman tason Owner oikeuksia.

5.2 Palvelupyyntöprosessi (JYU TIM)

Prosessin kulkua JYU TIM -instanssilla voi kuvata seuraavalla prosessidiagrammilla:

Palvelupyynnön tarkemmat vaiheet ovat

1. Palvelupyynnön avaus
   Käyttäjä voi tehdä palvelupyynnön kahdella vaihtoehtoisella tavalla:

   1. lähettämällä pyynnön sähköpostilla osoitteeseen tim@jyu.fi TAI
   2. GitHub-kortilla

   Pyynnön käsittelyä helpottaa yksityiskohtainen ongelman kuvaus. GitHub-sivustolta voi tarkastella olemassa olevia, avoimia ja suljettuja tikettejä.

2. Analysointi
   Ylläpito perehtyy palvelupyynnön sisältöön ja ottaa sen hoitaakseen tai ohjaa palvelupyynnön tarvittaessa toiselle asiantuntijalle sen kuuluessa paremmin toisen asiantuntijan osaamis- tai vastuualueelle. Ylläpito voi myös luoda sähköpostilla käyttäjältä tulleen palvelupyynnön johdosta GitHub-tiketin.

3. Vastaaminen
   Asiantuntija vastaa käyttäjän lähettämään palvelupyyntöön. Käyttäjä pidetään ajan tasalla pyynnön etenemisestä ja mahdollisista muista toimenpiteistä. Käyttäjältä saatetaan pyytää lisätietoja, jotka analysoidaan myös. Sähköpostilla avatut viestiketjut siirtyvät usein suoraan ensimmäiseksi vastanneen ylläpitoryhmän jäsenen vastattavaksi.

4. Ohjeistus ja toimenpiteiden määräys
   Palvelupyynnön luonteesta riippuen ylläpito antaa suoraan käyttäjälle tarvittavat ohjeistukset tai toimintaohjeet asian ratkaisemiseksi. Tarvittaessa ylläpito itse toteuttaa tarvittavat toimenpiteet.

5. Toimenpiteiden suoritus
   Ylläpito tai käyttäjä suorittaa tarvittavat toimenpiteet palvelupyynnön toteuttamiseksi.

6. Pyynnön täyttyminen
   Palvelupyyntö on selvitetty ja suljettu. Ensimmäisen tavan mukaan avatut palvelupyynnöt katsotaan sulkeutuneeksi, kun pyyntö on täyttynyt ja sitä koskeva viestiketju pysähtynyt. GitHub-kortilla avatun palvelupyynnön status määritellään suljetuksi, kun pyyntö on katsottu täyttyneeksi.

Käyttäjä voi koska tahansa keskeyttää palvelupyynnön jättämällä pyynnön keskytyksestä syntyneeseen viestiketjuun. Pyynnön voidaan myös nähdä keskeytyneen, mikäli viestiketjun jatkuminen pysähtyy käyttäjän toimesta.

5.3 Yleiset palvelupyynnöt

Palvelupyynnöt voi jakaa JYU TIM -instanssilla kahteen luokkaan: avun- ja opastuspyyntöihin sekä sisällön päivityspyyntöihin.

5.3.1 Avunpyynnöt ja opastuspyynnöt

Palvelupyynnöt voivat olla luonteeltaan avunpyyntöjä tai opastuspyyntöjä, esimerkiksi liittyen TIM-dokumenttien muokkaukseen/luomiseen.

Esimerkkejä pyynnöistä:

• sivujen poistaminen ja palauttaminen
• kuvion luominen
• kurssin videosisältö ei toimi

Avunpyynnöt voivat olla myös kurssien sisältöön liittyviä tai dokumenttien omistajille kuuluvia pyyntöjä. Tällaiset eivät varsinaisesti kuulu TIM-tiimin asiantuntijoille ja ne ohjataan yleensä järjestelmän toimesta suoraan asianomaisille henkilöille, kuten kurssin opettajille.

5.3.2 Päivityspyynnöt ja muutokset

Päivityspyyntöjä ja muutoksia koskevat palvelupyynnöt pitävät sisällään TIM-palvelun sisältöön kohdistuvia toimenpiteitä: päivitys- tai muutostarpeita tai -ehdotuksia. Näitä voivat olla esimerkiksi erilaiset lisäykset, poistot ja muutokset, kuten esimerkiksi Pythonin versiopäivityksen toteuttaminen.

Esimerkkejä pyynnöistä:

• Kuvien ja kaavojen numerointi