TrialInfo
=========

TrialInfo ist ein Auswertungssystem für Trial Motorrad- und Fahrrad-
Wettbewerbe. Es unterstützt alle wesentlichen Schritte zur Verwaltung einzelner
Veranstaltungen und zur Erstellung von Gesamtwertungen über mehrere
Veranstaltungen.

Folgende Funktionen werden unterstützt:

 * Anlegen, Ändern und Löschen von Veranstaltungen.  Konfigurieren von
   Veranstaltungen (Wertungen, Klassen, befahrene Sektionen, usw.).

 * Anlegen und Ändern von Fahrern, Zuweisen von Startnummern, Auswahl der
   Starter einer Veranstaltung.

 * Verwaltung von Gruppen und Erstellung von Gruppenwertungen.

 * Erfassung der Ergebnisse (Punkte, Ausfall, Stechen, Start- und Zielzeit).

 * Erstellung verschiedener Fahrerlisten und von Ergebnislisten online und
   als PDF-Dateien.

 * Definition von Veranstaltungsreihen (Klassen, Anzahl der Läufe und
   Streichresultate, Startnummernänderungen zwischen Veranstaltungen).

 * Import von und Export auf Dateien.  (Der Import vom und Export in das
   Programm TrialTool, http://www.ortwinsann.de/trialtool/, von Ortwin Sann
   war in einer älteren Version möglich, wird derzeit aber nicht benötigt,
   und daher nicht unterstützt.)

 * Import direkt von einem Server. Laufende Synchronisierung auf einen Server.

 * Präsentationsmodus (für einen externen Bildschirm).

 * Online-Registrierung.

Das System ist komplett über einen Web-Browser bedienbar.  Es kann von mehreren
Geräten aus gleichzeitig verwendet werden. Wird dabei versucht, die selben
Daten mehrfach zu verändern, dann werden diese Konflikte erkannt, und es kommt
zu Fehlermeldungen.


Systemvoraussetzungen
=====================

 * Ein einigermaßen aktuelles Linux-System.  (Dieses System kann auch
   innerhalb einer virtuellen Maschine laufen.)

 * Die Pakete nodejs (https://nodejs.org/) und npm (https://www.npmjs.com/).

 * Die Datenbank MySQL (bzw. MariaDB).


Konfiguration
=============

Datenbank
---------

In MySQL ist wichtig, dass eine transaktionsfähige Datenbank-Engine (InnoDB,
nicht MyISAM) verwendet wird.


  Beispiel
  --------

  $ mysqladmin --user=root password
  New password: 
  Confirm new password: 

  $ mysql --user=root --password
  Enter password: 
  > CREATE DATABASE trialinfo CHARACTER SET utf8;
  > CREATE USER 'trialinfo'@'localhost' IDENTIFIED BY 'password';
  > CREATE USER 'trialinfo'@'%' IDENTIFIED BY 'password';
  > GRANT ALL PRIVILEGES ON trialinfo.* TO 'trialinfo'@'%';


Die anfängliche Datenbankstruktur lässt sich danach folgendermaßen erzeugen:

  $ mysql --user=trialinfo --password=password < create-db.sql

  /etc/my.cnf.d/server.cnf
  ------------------------
  Add STRICT_TRANS_TABLES to sql_mode:

  [server]
  sql_mode=STRICT_TRANS_TABLES,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION

Nach Veränderungen kann man create-db.sql folgendermaßen aktualisieren:

  $ mysqldump --user=root --password --dump --no-data --skip-comments > create-db.sql


Herunterladen und erzeugen diverser Dateien
-------------------------------------------

Um einige Dateien wie Angular.js herunterzuladen, wird Make verwendet:

  $ make install


Backend konfigurieren
---------------------

Die Scripts lassen sich über die Datei backend/config.json konfigurieren.  Die
Einstellungen dort betreffen Dinge wie die Zugriffsdaten auf die Datenbank.

Achtung: Diese Datei muss per Hand erzeugt werden, bevor die Applikation
gestartet werden kann.  Eine Vorlage dafür befindet sich in der Datei
backend/config.json.in.


Backend starten
---------------

Das Backend kann mit "make start" in einem Testmodus gestartet werden, und mit
"make serve" in einem Produktionsmodus.

Danach kann über einen Web-Browser auf TrialInfo zugegriffen werden.

Im Betrieb kann der Start z.B. über systemd erfolgen.


Web Server
----------

Die im Backend implementierte Web-Applikation beinhaltet alle Funktionen, um
Veranstaltungen durchführen zu können.  Um mehere Instanzen auf dem gleichen
Server laufen zu lassen, bietet es sich an, dafür Apache zu verwenden, und
Apache als Proxy zum Backend zu verwenden.

  Beispielkonfiguration für Apache:

    <VirtualHost *:80>
	DocumentRoot /home/agruen/trialinfo/htdocs
	ServerName www.trialinfo.at

	<LocationMatch ".*">
	    Require all granted
	</LocationMatch>

	<Directory "/home/agruen/trialinfo/htdocs">
	    Options Indexes
	    AllowOverride All
	</Directory>

	<LocationMatch "^/(.*)$">
	    ProxyPassMatch "http://localhost:3080/$1"
	</LocationMatch>
    </VirtualHost>

Je nach Konfiguration kann es sein, dass die Konfiguration für TrialInfo mit
dem Befehl "a2ensite" aktiviert werden muss.


SELinux
-------

  $ semanage fcontext -a -t httpd_sys_content_t '/home/agruenba/trialinfo/htdocs'(/.*)?'
  $ restorecon -r /home/agruenba/trialinfo/htdocs
  $ semanage port -a -t http_port_t -p tcp 3080

  Wenn die Daten in einem Home Directory liegen, lässt sich SELinux nicht
  leicht so konfigurieren, dass die CGI-Scripts funktionieren.  Sonst sollte
  folgendes klappen:

  So kann man selbst erstellte File Context-Regeln anzeigen:

  $ semanage fcontext -l -C


Systemd
-------

  /etc/systemd/system/trialinfo.service
  ------------------------------------------
  [Unit]
  Description=TrialInfo

  [Service]
  ExecStart=/usr/bin/node index.js
  WorkingDirectory=/var/www/trialinfo/backend/dist
  StandardOutput=journal
  SyslogIdentifier=trialinfo
  User=trialinfo
  Group=trialinfo
  Environment=NODE_ENV=production
  Environment=TRIALINFO=systemd


  /etc/systemd/system/trialinfo.socket
  -----------------------------------------
  [Socket]
  ListenStream=3080
  Service=trialinfo.service

  [Install]
  WantedBy=sockets.target


  $ systemctl daemon-reload

  $ systemctl enable trialinfo.socket
  - oder -
  $ systemctl enable trialinfo-secure.socket

  $ journalctl -u trialinfo
  $ journalctl -f -u trialinfo


Git post-receive hook
---------------------

    export GIT_WORK_TREE=/var/www/trialinfo
    git checkout -f

    make -C $GIT_WORK_TREE install
    make -C $GIT_WORK_TREE build

    sudo /bin/systemctl stop trialinfo.service
    sudo /bin/systemctl restart trialinfo.socket


Apache-Module
-------------

Auf manchen Systemen wie Ubuntu 15.04 müssen die verwendeten Apache-Module
mit folgendem Befehl aktiviert werden:

  $ a2enmod rewrite.load


RPM-Paket bauen
===============

$ make release


Veranstaltungsverwaltung
========================

Nach der Konfiguration der verschiedenen Komponenten ist die
Veranstaltungsverwaltung im Pfad /admin/ auf dem Web-Server verfügbar.


Rechtemodell und Rechteverwaltung
=================================

Auf den Administrationsbereich haben nur Benutzer mit dem "admin"-Flag Zugriff.

Dabei haben Benutzer mit dem "super_admin"-Flag vollen Zugriff auf alle
Veranstaltungen und Veranstaltungsreihen.  Die anderen Benutzer sehen nur die
Veranstaltungen und Veranstaltungsreihen, auf die sie zumindest Lesezugriff
haben.

Legt ein Benutzer eine neue Veranstaltung oder Veranstaltungsreihe an, dann
bekommt er dort Schreib-/Lesezugriff.

Weiters lassen sich direkt in der Datenbank zusätzliche Rechte vergeben, es
lassen sich Gruppen von Benutzern definieren, und es kann definiert werden, wie
Berechtigungen zwischen Veranstaltungen vererbt werden, wenn eine Veranstaltung
auf Basis einer anderen Veranstaltung erzeugt wird.

Veranstaltungen erben auch die Zugehörigkeit zu Veranstaltungsreihen von ihrer
Basisveranstaltung, sofern der Benutzer Schreibzugriff auf die jeweilige
Veranstaltungsreihe hat.


Reihung in der Jahreswertung
============================

Fahrer werden zunächst anhand ihrer Gesamtpunkteanzahl gereiht, wobei die
Punkte aus Streichresultaten abgezogen sind.

Bei gleichem Punktestand werden alle erzielten Ergebnisse inklusive der
Streichresultate verglichen.  Der Fahrer mit mehr guten Platzierungen, also mit
mehr ersten Plätzen, oder mit mehr zweiten Plätzen bei gleicher Anzahl erster
Plätze, usw., gewinnt.

Danach gewinnt der Fahrer mit mehr Streichpunkten.

Diese Reihung kann in den Einstellungen der Veranstaltungsreihe überschrieben
werden, indem die Reihenfolge bei Punktegleichstand explizit definiert wird.


WeasyPrint
==========

WeasyPrint Wird verwendet, um am Server HTML nach PDF zu konvertieren.
Weasyprint ist zwar speziell für die Ergebnislisten mit ihren großen Tabellen
sehr langsam, dafür erzeugt es aber einen ordentlichen Seitenumbruch, was z.B.
WebKit-basierte Lösungen wie wkhtmltopdf nur sehr mangelhaft beherrschen.

  $ yum install weasyprint


Lizenz
======

Dieser Text und die Programme stehen under der GNU Affero General Public License
Version 3, http://www.gnu.org/licenses/agpl-3.0.html.