Shaman-järjestelmän asennusohje
-------------------------------
Versio 0.0525
Päiväys 25.5.2005
Copyright © 2005 SHAMAN-projekti.


1. Tarvittava laitteisto ja ohjelmisto.

Shaman-järjestelmä (versio 0.0525) tarvitsee toimiakseen Linux-palvelimen,
jossa on asennettuina PostgreSQL-tietokannan hallintaohjelmisto ja Perl-tulkki.
WWW-pohjainen käyttöliittymä tarvitsee lisäksi Apache-palvelinohjelmiston HTTP
ja HTTPS-pyyntöjen käsittelemiseen.

Järjestelmä on kehitetty käyttäen PC-laitteistoa (1.4 GHz suoritin, 512 MT
keskusmuistia). Koneen käyttöjärjestelmänä on Linux Fedora Core 2, Perl-tulkin
versio on 5.8.3 ja PostgreSQL-tietokannanhallintaohjelmiston versio on 7.4.7.

Varsinaisia laitteistovaatimuksia Linux-käyttöjärjestelmän ja muiden
ohjelmistojen asettamien vaatimusten lisäksi ei ole. Suurempi keskusmuistin
määrä ja nopeampi prosessori parantavat järjestelmän suoritustehokkuutta.

Shaman-järjestelmä muodostuu Perl-kielisistä moduuleista, käyttöliittymän
muodostavasta skriptistä users.cgi ja tmpl-päätteisistä template-tiedostoista.

Shaman-projektin toteuttamat moduulit tarvitsevat toimiakseen moduulit DBI ja
DBD::Pg. Käyttöliittymä tarvitsee Shaman-projektin toteuttamien moduulien
lisäksi Perl-moduulit CGI, CGI::Session ja HTML::Template.

Moduulien asennuspaketit ja lisätietoa moduuleista on saatavissa seuraavilta
sivuilta:

   DBD:Pg           http://search.cpan.org/~dbdpg/DBD-Pg-1.42/
   DBI              http://search.cpan.org/~timb/DBI-1.48/

   CGI              http://search.cpan.org/~lds/CGI.pm-3.10/
   CGI::Session     http://search.cpan.org/~sherzodr/CGI-Session-3.95/
   HTML::Template   http://search.cpan.org/~samtregar/HTML-Template-2.7/


2. Tarvittavien ohjelmistojen asennus.

Linux-käyttöjärjestelmän, Perl-tulkin, PostgreSQL:n ja muiden kuin Shaman-
projektiryhmän toteuttamien moduulien asennusohjeet toimitetaan ko.
ohjelmistojen mukana. Lisätietoa em. ohjelmistoista saatavana osoitteista:

   Linux        http://www.linux.org
   PostgreSQL   http://www.postgresql.org
   Perl         http://www.perl.org

Käyttöliittymän tarvitsemat moduulit CGI, CGI::Session ja HTML::Template
on suositeltavaa asentaa suoraan järjestelmään, mutta tarvittaessa niitä
voidaan käyttää myös suoraan itse määritetystä hakemistosta (ks. luku 4).


3. Tietokannan asennus.

Shaman-järjestelmän käyttämän tietokannan luonti edellyttää, että PostgreSQL on
asennettu onnistuneesti.

Järjestelmälle luodaan halutun niminen tietokanta käyttäen esimerkiksi
komentorivipohjaista psql-ohjelmaa tai WWW-pohjaista hallintatyökalua.

Onnistuneen tietokannan luonnin jälkeen suoritetaan yllä mainittuja työkaluja
käyttäen CD-ROMin hakemistossa tietokanta tiedostossa luontilauseet.txt
olevat luontilauseet. Vaihtoehtoisesti luontilauseiden sijaan voidaan suorittaa
tiedosto shamankanta.out, joka sisältää tietokannan luontilauseiden lisäksi
useimpiin tietokannan tauluihin laitettua testidataa.


4. Moduulien ja käyttöliittymän asennus.

Asennus suoritetaan purkamalla CD-ROMin hakemistosta "Asennus"
löytyvä shaman_install.tar.gz asennuspaketti haluttuun palvelimen hakemistoon.
Asennuspaketti luo hakemistoon alihakemiston nimeltään shaman, jonka alla on
seuraavanlainen hakemistorakenne:

+---lib
|   |   Lang.pm
|   |   SystemConfig.pm
|   |
|   +---data
|   |       Log.pm
|   |       Sql.pm
|   |
|   \---system
|           Account.pm
|           Accounts.pm
|           History.pm
|           Group.pm
|           Groups.pm
|           Pending.pm
|           Person.pm
|           Persons.pm
|           Resource.pm
|           Resources.pm
|           ShamanSql.pm
|           ShamanSqlLoad.pm
|           ShamanSqlSave.pm
|           ShamanSqlRemove.pm
|           ShamanSqlTypes.pm
|           ShamanSqlHierarchy.pm
|           ShamanSqlSearch.pm
|           Types.pm
|
\---user_interface
            addgroup.tmpl
            adduser.tmpl
            edituserdata.tmpl
            personparameter.tmpl
            searchuser.tmpl
            soihtu.gif
            tyyli.css
            users.cgi
            viewuserdata.tmpl

Hakemisto lib on kopioitava sellaiseen hakemistoon, josta hakemistossa
user_interface oleva tiedosto users.cgi voi lukea hakemiston lib sisällä olevia
tiedostoja.

Hakemisto user_interface on kopioitava sellaiseen hakemistoon, jolle on
järjestelmän asetuksissa mahdollistettu kuva- ja tyylitiedostojen näyttäminen
sekä CGI-skriptien ajo-oikeus.


5. Asennuksen viimeistely

Tiedostossa SystemConfig.pm määritellään järjestelmän toimintaan vaikuttavia
asetuksia.

Järjestelmän toiminnan kannalta välttämättömiä asetustiedostoon tehtäviä
muutoksia ovat tietokanta- ja lokiasetusten asettaminen vastaamaan
järjestelmän suoritusympäristöä.

Käytettävän tietokannan asetukset määritetään seuraavissa kohdissa:

      "username" => "username_here",
      "password" => "password_here",
      "hostname" => "hostname_here",
      "database" => "databasename_here",
      "port"     => "portnumber_here"


Lokitietojen tiedostonimi määritellään seuraavasti:

      'FILENAME'      => "tiedostonimi[määritteet]"

Mahdollisia parametreja tiedoston nimen määritteelle ovat DATE (kertoo lokin
kirjauksen päivämäärän), TIME (lokin kirjauksen kellonaika) ja ERRTYPE
(virheen tyyppi). Määritteet voivat olla samanaikaisesti käytössä, eli
esimerkiksi rivi

      'FILENAME'      => "LOG-ERRTYPE-DATE-TIME"

on mahdollinen.

Lokitiedostojen tallennushakemisto määritellään seuraavalla rivillä:

      'PATH'          => "/lokitiedostojen/hakupolku/"

HUOM! Hakemistopolun viimeinen merkki on oltava kauttaviiva "/". Samoin
hakemistopolku on oltava olemassa, eli hakemistoa ei luoda lokitietoja
kirjoitettaessa. Hakemistoon on oltava kirjoitusoikeus Apache-käyttäjällä.

Järjestelmä on suotavaa asentaa sellaiseen palvelimen hakemistoon, johon
kohdistuva liikenne salataan.

Järjestelmän toimintaa kuvaavat näytölle tulostettavat tulostukset voidaan
asettaa päälle tai pois seuraavalla rivillä:

      'PRINT_TO_SCREEN'   => 1 # 0=Don't show, 1=show

Jos tietokannan taulujen tai kenttien nimet ovat muuttuneet
Shaman-projektin toteuttamasta tietokannasta, tulee muutokset päivittää
SystemConfig.pm-tiedoston ShamanSql-osuuteen.

Tiedoston users.cgi ja Shaman-projektin toteuttamien moduulien keskinäiseen
sijaintiin voidaan vaikuttaa skriptitiedoston users.cgi ensimmäisellä
koodirivillä olevalla use lib -käskyllä. Skriptin users.cgi on tiedettävä,
mistä projektin tuottamat moduulit löytyvät.

Template-tiedostot sekä tiedstot tyyli.css ja soihtu.gif on sijoitettava samaan
hakemistoon users.cgi:n kanssa. Mikäli moduuleita CGI, CGI::Session ja
HTML::Template ei ole asennettu järjestelmään, voidaan niitä käyttää suoraan
hakemistoista määrittelemällä käytettävät hakemistot tiedoston users.cgi alussa
olevilla use lib -riveillä.


6. Ongelmatilanteet

Mikäli asennuksessa ilmenee ongelmia ylläkuvattujen toimenpiteiden
huolellisesta suorittamisesta huolimatta, ota yhteyttä Shaman-projektin
jäseniin:

Marko Andersson maenande@cc.jyu.fi
Mika Rinkinen   mikarin@cc.jyu.fi
Matti Törmä     matorma@cc.jyu.fi
Timo Valonen    tijovalo@cc.jyu.fi