# timOhjeet

TIM-järjestelmän asentaminen

TIM-järjestelmä koostuu TIM-lähdekoodista sekä koodia ajavista palveluista. Palvelut ja kaikki ajonaikaiset riippuvuudet ovat pakattu Docker-konteiksi helpottamaan asentamista. TIM-järjestelmän asentaminen siten koostuu kolmesta vaiheesta: riippuvuuksien asentaminen, lähdekoodin lataaminen ja TIM-järjestelmän ylösajo.

Tämä ohje koskee sekä TIM-järjestelmän integroijia sekä TIM-järjestelmän kehittäjiä. Kehittäjäkohtaiset ohjeet erotetaan Kehittäjät-tekstillä.

1. Järjestelmävaatimukset

TIM-instanssin vaatimukset järjestelmällä riippuvat odotetusta käyttäjämäärästä. Alla olevat vaatimukset ovat arviot JYU-TIM-instanssin perusteella:

Laitteisto

  • Levy: SSD, min. 25 GB, josta 18 GB tulee olla ensisijaisella levyllä
  • RAM: min. 8 GB + 4 GB jokaista 100 aktiivista käyttäjää kohti
    • Kehittäjät: suositus on min. 16 GB, jotta kaikki kehitysaikaiset ohjelmat voi ajaa
  • CPU: x86_64 (eli Intel x86 -yhteensopiva 64-bittinen prosessori tai sen emulaattori); 1 ydin jokaista 100 aktiivista käyttäjää kohti
    • Kehittäjät: Kehitystilassa TIM ajetaan aina yhdessä prosessissa, mutta moniydinprosessori on suositus kehitysohjelmia varten

Käyttöjärjestelmä

TIM voi käyttää missä tahansa järjestelmässä, josta löytyy tuki Docker-ohjelmalle. Järjestelmäkohtaiset vaatimukset:

  • Linux: mikä tahansa jakelu, jossa käytössä Linux kernel 3.10 tai uudempi
    • Voit tarkistaa oman jakelun kernelin versio ajamalla uname -r
    • Linux on ensisijainen järjestelmä, jossa tuotantoinstanssi tulisi ajaa
  • Windows: Windows 10 21H1 (build 19041) tai uudempi, Windows 11 21H2 tai uudempi
    • Windows-asennus vaatii, että laitteisto tukee Hyper-V -virtualisointia. Voit tarkistaa tämän ajamalla Windowsilla systeminfo-komento ja katsomalla sen ilmoittava Hyper-V Requirements-kohtaa.
  • macOS: macOS 10.15 (Catalina) tai uudempi
    • Apple silicon -prosessorilla varustetut laitteet tarvitsevat Rosetta 2 -sovellusta (macOS:n pitäisi asentaa sen automaattisesti)

2. Pika-asennusskripti

Jos

  • asennat TIM-järjestelmän Linux-koneelle (Ubuntu, RHEL 8+, CentOS 8+, Arch Linux / Manjaro), ja
  • asennat TIM-järjestelmän tuotantokäyttöön (eli EI kehittäjät)

voit käytää pika-asennusskriptia:

curl -sL https://get.tim.education/linux.sh | bash -s - --profile prod

Skripti asentaa automaattisesti kaikki riippuvuudet tuotantoajoa varten sekä käynnistää minimaalisen TIM-instanssin. Asennuksen jälkeen kannattaa muokata tim.conf omien tarpeiden mukaan.

Voit tutustua pika-asennusskriptin koodiin sen GitHub-repossa: TIM-JYU/tim-installscripts.

2.1 Kehitysympäristön automaattinen asennus (kokeellinen!)

3. Riippuvuuksien asentaminen

Uusin Python-versio on nyt 3.11.

DZ: Kiitos huomiosta! Muotoilua korjattu osoittamaan, että parempi on asentaa uusin TIMin käytössä oleva versio. Tällä hetkellä se on 3.10, mutta ennen syksyä pyritään päivittämään se 3.11. Kehityksessä voi yrittää käyttää 3.11, mutta vastaan saattaa tulla yllätyksiä asennuksen kanssa.

— 11 Aug 23 (edited 11 Aug 23)

TIM-järjestelmä tarvitsee seuraavat ohjelmat asennettuna:

  • Docker Engine ja Docker Compose
    • Kehittäjät: Voit asentaa sen sijaan Docker Desktop, joka sisältää kaikki tarvittavat Docker-riippuvuudet
  • Python 3.6 tai uudempi (kehittäjät: asenna uusin TIM käytössä oleva versio tällä hetkellä 3.10; uudemmat versiot saattavat toimia myös)
    • Windows: Valitse asennusohjelmassa Add Python to environment variables
  • Git 1.8 tai uudempi
  • Kehittäjät: Node.JS (mikä tahansa LTS-versio) ja NPM 6.x
    • Huom: NPM:n versio voi oletuksella olla eri kuin 6.x. Katso lisäohjeet alempana.
  • Mikä tahansa shell-tulkki; alla lista testatuista ja toimivaksi todetuista tulkeista:
    • Linuxin POSIX-yhteensopivat shell-tulkit: bash, zsh, fish, sh, ...
    • macOS:n sisäänrakennettu komentorivi
    • Git Bash (Windows)
    • MINGW ja MSyS shell-tulkit (Windows)
    • WSL2 Bash (Windows)

Muut ohjelmat asentuvat automaattisesti TIMin asennuksen yhteydessä. Voit katsoa kaikkien TIMissa käytettävien ohjelmien selitykset palveludokumentaatiossa.

Alla olevat riippuvuuskohtaiset ohjeet tarkentavat eri ohjelmien asentamista sekä konfigurointia.

3.1 Kehittäjät: Docker Desktop

Docker Desktop sisältää valmiiksi kaikki riippuvuudet Dockerin käyttöönottoon kehityksessä.

3.1.1 Linux

Viralliset asennusohjeet

  • Tarkista ensin, löytyykö Docker jakelun omasta pakkaushallinnasta
  • Docker Desktopin sijaan voi asentaa Docker + Docker Compose erikseen. Suurin osa jakeluista tarjoaa erikseen docker-pakkauksen sekä docker-compose-pakkauksen
  • Jos jakelusta ei löydy docker-composea pakkauksena, voit edetä seuraavasti:
    • Aja docker compose version. Jos saat version (esim. Docker Compose version v2.x.x), sinulla on jo valmiiksi Docker Compose
    • Muussa tapauksessa voit asentaa skriptin käsin: Install Compose manually (hae sivulta Compose standalone, joka on helpoint tapa asentaa compose)

3.1.2 Windows

Lataa asennusohjelma

Viralliset asennusohjeet

  • Varmista asennusohjelmassa, että ruksi Use WSL 2 instead of Hyper-V on valittu
  • Docker Desktop -asennusohjelman pitäisi automaattisesti konfiguroida tietokone toimimaan virtualisoinnin kanssa. Jos tämä ei tapahdu, voi tehdä tämän käsin: Dockerin viralliset ohjeet
  • Docker Desktop -asennusohjelma asentaa myös Windows Subsystem for Linux 2 (WSL2) automaattisesti. Jos tämä ei onnistunut jostain syystä, voi asentaa WSL2 käsin Microsoftin ohjeilla
  • Docker Desktop saattaa pyytää käynnistää järjestelmä muutaman kerran uudelleen sekä asentaa lisäriippuvuuksia (esim. WSL2 Linux kernel). Seuraa Docker Desktop -asennusohjelman ohjeita

3.2 Kehittäjät: NodeJS

  • Linuxilla Node.JS:n LTS (long-term support) versiot ovat usein saatavilla suoraan pakkaushallinnasta

  • TIM-järjestelmä käyttää kehityksessä toistaiseksi NPM 6.x johtuen uudempien versioiden eri oikeus- ja tehokkuusongelmista. Tarkista ensiksi oma NPM-versio ajamalla

    npm --version

    jos tulosteena tulee mikä tahansa kuin versio 6, versio pitää alentaa komennolla

    npm install --global npm@6

    Tarkista vielä lopuksi, että versio asettui oikein.

  • Huomaa, että TIM tarvitsee NPM version 6! Jos tarvitset omaa kehitystä varten eri NPM-version, voit käyttää NVM for Windows tai nvm.sh.

  • Lisähuomio: nk. rolling release pakettihallintaa käyttävissä Linux-jakeluissa (mm. Arch, Manjaro, Gentoo) nvm saattaa mennä rikki kun pakettihallinta asentaa päivityksenä uuden version Node.js:stä. Silloin ainoana ratkaisuna saattaa olla poistaa nvm ja sen tekemät muokkaukset virallisten ohjeiden mukaan, asentaa Node.js/NPM uudelleen käyttöjärjestelmän paketinhallinnan kautta, ja sitten downgradettaa versioon 6.x. Jos TIMia käynnistäessä bdw-skripti kaatuu virheeseen

    TypeError: Class extends value undefined is not a constructor or null

    tarkista virhetulosteen oheen tuleva merkintä Node.js versiosta (vertaa vain tähän virhetulosteen versioon, komentorivin tarkistus npm --version saattaa rikkinäisestä nvm:stä johtuen edelleen ilmoittaa muuta). Todennäköisesti kyse on siitä, että bdw yritetään ajaa väärällä npm:n versiolla. Virhetulosteen ilmoittaman version pitäisi olla 14.x.x, jos ensimmäinen numero on isompi kuin 14, on nodejs/npm:n versio väärä.

4. TIM-lähdekoodin lataaminen

Riippuvuuksien asentamisen jälkeen voi ladata TIM-järjestelmän lähdekoodi. TIM-järjestelmä ladataan GitHub-reposta:

  1. Kehittäjät: Luo SSH-avaimet ja asenna ne GitHubiin.

  2. Mene hakemistoon, johon TIM asennetaan

  3. Aja shell-tulkilla

    Jos sinulla on puskuoikeus TIM-repoon (kehittäjät):

    git clone git@github.com:TIM-JYU/TIM.git tim

    Jos sinulla ei ole puskuoikeutta:

    git clone https://github.com/TIM-JYU/TIM tim

5. Järjestelmän konfigurointi ja ylösajo

TIM-järjestelmän konfigurointi tehdään käyttämällä TIM-komentorivityökalu (TIM CLI).

  1. Avaa shell-tulkki ja mene ladattuun TIM-instanssin kansioon

  2. Aja ./tim setup

  3. Seuraa konfigurointiohjelman ohjeet

    1. Valitse ajoprofiili. Käytännössä tähän on kaksi vaihtoehtoa:
      • prod: konfiguroi TIM-instanssi "tuotantokäyttöön"
      • dev: konfiguroi TIM-instanssi kehityskäyttöön (kehittäjille)
    2. prod-profiilissa pyydetään syöttämään lisäasetuksia, kuten TIM-instanssin osoite ja instanssin käyttämät portit

  4. Seuraa asennuksen etenemistä: TIM lataa Docker-imaget, kääntää selainkoodit sekä ajaa kaikki palvelut ylös

    Jos joku vaihe epäonnistuu, voit myöhemmin ajaa konfiguroinnin uudelleen komennolla ./tim setup --force

Tämän jälkeen TIM-järjestelmä on valmis ja käynnissä. Testaa, että pääset TIMin etusivulle:

  • prod-profiilissa osoite on konfiguroitu osoite
  • dev-profiilissa (kehittäjät) osoite on http://localhost
    • Jos kaikki toimii, näet "TIM Caddy is running!" -viestin

5.1 Uuden käyttäjän luominen

TIMissa on valmiiksi kolme testikäyttäjää (katso ylläpito-ohje) muttei ylläpitokäyttäjää.

Tee uusi ylläpitotunnus komennolla

./tim run flask user create

6. Yleisimmät ylläpitokomennot

TIM-instanssin ylläpito tehdään ensisijaisesti TIM CLI -työkalulla (./tim-skripti TIM-hakemistossa).

Yleisimmät hyödylliset komennot peruskäyttöön:

  • ./tim up: käynnistää kaikki kontit, tarvittaessa käynnistäen niitä uudelleen (esim. konfiguraation muutoksen takia)
  • ./tim restart: käynnistää kaikki kontit uudelleen
  • ./tim update all: tekee täydellisen TIM-järjestelmän päivityksen (lataa kontit, kääntää JavaScriptit)
    • Huom: Tämä ei päivitä itse lähdekoodia. Voit tehdä tämän esim. git pull tai vastaavalla tavalla.

Harvinaisemmat, mutta silti hyödylliset komennot

  • ./tim js: kääntää JavaScript-koodin uudelleen
  • ./tim dc down: ajaa TIM-järjestelmän alas
  • ./tim run flask: TIM-plavelun ylläpitokomennot. Sisältää komennot esim. (ylläpito)käyttäjien luomiseen ja hallintaan.

Lisäkomentoja löytyy ajamalla ./tim --help sekä tutustumalla ylläpito-ohjeisiin

7. Seuraavaksi

These are the current permissions for this document; please modify if needed. You can always modify these permissions from the manage page.