Installation von OSIRIS

Installieren unter Linux

Um OSIRIS zu installieren, braucht ihr einen Webserver (Apache2 z.B.), auf dem MongoDB installiert ist. Ich habe WAMP-basierte Windows-Systeme ebenso wie Linux (Rocky Linux) ausprobiert und es funktioniert auf beidem. In dieser Anleitung gehe ich aber davon aus, dass ihr ein Linux-System verwendet. Die Code-Beispiele funktionieren so wahrscheinlich nur auf CentOS/Rocky Linux. Bei anderen Linux-Distributionen wird teilweise mit APT gearbeitet und die Pakete können anders heißen.

Server und Datenbank: Vorbereitung auf OSIRIS

Zuerst muss die Datenbank installiert werden. Folgt dazu am besten den Anweisungen auf der MongoDB-Webseite, um MongoDB Version 5.X zu installieren.

Außerdem benötigt ihr natürlich PHP 8.X sowie ein paar weitere dazugehörige Module, wie zum Beispiel PEAR, LDAP und natürlich den MongoDB-Driver. Bei mir hat das wie folgt funktioniert (Auf CentOS/Rocky Linux):

sudo yum install -y mongodb-org

sudo yum -y update

sudo yum -y install gcc php-pear php-devel
sudo yum install php-ldap

sudo pecl install mongodb-1.12.0

In der PHP-Config müssen nun noch die richtigen Pakete angeschaltet werden. Bei mir hat es nur mit absoluten Pfaden funktioniert (der muss vermutlich angepasst werden):

add extension=/usr/lib64/php/modules/mongodb.so   
add extension=/usr/lib64/php/modules/zip.so   

Nun könnt ihr MongoDB starten und am besten den Webserver neu starten.

sudo systemctl start mongod
sudo systemctl restart php-fpm.service

Zuletzt braucht ihr noch Composer. Darüber werden die beiden Module für die MongoDB-Erweiterung sowie PHPWord heruntergeladen. Letzteres benötigt ihr für den Export von Berichten.

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

# Mittels Composer werden nun alle Pakete installiert
composer require mongodb/mongodb:1.12.0
composer require phpoffice/phpword
composer require renanbr/bibtex-parser

# oder:
composer update

Falls es bei euch nicht klappt, versucht mal --ignore-platform-reqs zu allen Aufrufen hinzuzufügen

OSIRIS mit Git installieren

OSIRIS installiert ihr am besten mittels Git, dadurch könnt ihr euch neue Updates mit nur einer Zeile Code direkt aus GitHub ziehen. Der erste Schritt ist also Git zu installieren. Danach könnt ihr folgendes tun:

# Hier muss der Pfad zu dem Webserver angpasst werden
cd /var/www/html 

# Als nächstes wird geklont
# Der Punkt ist wichtig, damit kein Unterordner erstellt wird
git clone https://github.com/JKoblitz/osiris.git . 

Sollte es ein Update geben, könnt ihr dies mit git pull einspielen.

Installation unter Windows (for Dummies)

Vielen Dank Robin Lange vom IWH, der uns folgende Installationsanleitung für Windows zur Verfügung gestellt hat. Sie ist für jemanden geschrieben, der vorher noch nie mit Webservern zu tun hatte.

Anleitung

1. XAMPP downloaden und installieren. Hierbei ist wichtig, dass man eine Version mit PHP 8.1.x wählt (PHP 8.2 wird noch nicht von dem Mongo PHP Driver für Windows unterstützt). Wenn man möchte, dass die Webseite später für alle im Netzwerk/Wlan erreichbar ist, muss man am Ende der Installation den Zugriff aufs Netzwerk bei der Windows Firewall erlauben.
   Wenn XAMPP installiert ist, das Programm starten und bei Apache auf „Start“ klicken. Anschließend im Browser localhost eingeben. Jetzt sollte die Standardseite von Apache angezeigt werden.
2. Die MongoDB Datenbank als .msi runterladen und installieren. Die aktuellste Version (6.0) ist kompatibel mit OSIRIS. Im Installationsmenü alle Voreinstellungen so lassen.
3. Den MongoDB PHP Driver runterladen. Dazu in der Liste zur Version 1.13.0 scrollen und auf das blaue Windows Kästchen mit „DLL“ klicken. Unten in der Liste die Version PHP 8.1 Thread Safe für euer System auswählen (in der Regel x64). Die DLL Datei muss anschließend in den folgenden Ordner in eurem Xampp Verzeichnis kopiert werden: …\xampp\php\ext
   Wenn das geglückt ist, muss man den Treiber noch aktivieren. Dazu sucht man in dem Verzeichnis …\xampp\php nach der Datei php.ini (Achtung: wenn man sich unter Windows die Dateiendungen nicht anzeigen lässt, heißt die Datei evtl. einfach nur „php“. Da es mehrere solcher Dateien gibt, macht es Sinn, sich die Dateiendungen anzeigen zu lassen). Die Datei php.ini mit dem Editor der Wahl öffnen (zum Beispiel Notepad++) und die Zeile „extension=php_mongodb.dll“ hinzufügen. Der Übersicht halber sollte man die Zeile dort einfügen, wo auch die anderen extensions gelistet werden (ungefähr Zeile 950). Das ist aber nicht zwingend notwendig.
4. Git for Windows installieren. Im Installationsmenü alle Voreinstellungen so lassen. Anschließend den Ordner …\xampp\htdocs öffnen.
   In diesen Ordner wird die Webseite geladen. Dazu erst einmal alle Dateien, die sich in dem Ordner befinden, löschen. Dann Rechtsklick in das leere Verzeichnis und auf „Git Bash Here“ klicken. Es öffnet sich ein Kommandofenster. Da gibt man den folgenden Befehl ein: git clone https://github.com/JKoblitz/osiris.git Aufpassen! Den Code kann man hier nicht mit Strg+V einfügen. Wenn man das trotzdem versucht, bildet sich ein „unsichtbares Zeichen“ und der anschließende Code funktioniert nicht mehr. Man kann aber mit Linksklick den Code einfügen. Jetzt sollten alle Dateien aus dem Git Repository in das Verzeichnis kopiert werden.
5. Zu guter Letzt installiert man Composer mit der .exe Datei. Alle Voreinstellungen können so belassen werden. Anschließend die Windows Eingabeaufforderung (cmd) öffnen, indem man zum Beispiel in die Suchzeile „cmd“ eingibt.
   In dem Terminal muss man jetzt in das Xampp Verzeichnis der Webseite navigieren. Dies tut man mit dem Befehl cd. Wenn Xampp standardmäßig installiert ist lautet der Befehl cd C:\xampp\htdocs Wenn man sich jetzt im Verzeichnis befindet, gibt man Composer update ein. Wenn alles funktioniert, lädt Composer die fehlenden libraries nach.
6. Wenn nicht bereits geschehen, XAMPP starten und bei Apache auf „Start“ bzw. „Restart“ klicken. In den Browser localhost eingeben und die Webseite sollte erscheinen.
7. In der Config Datei können noch weitere Einstellungen vorgenommen werden (wie Administrator, ldap, Auth, …). Siehe dazu die den Abschnitt OSIRIS konfigurieren.

Installieren als Docker-Container

Vielen Dank an Lukas Ziersch, der die folgende Anleitung zur Installation von OSIRIS in einem Docker-Container zur Verfügung gestellt hat.

Neben den beiden unten gezeigten Dateien muss außerdem ein config-Ordner erstellt werden, der die angepassten Dateien CONFIG.php und .htaccess enthält. Mehr Details zu diesen Dateien findest du im Abschnitt zur Konfiguration.

Die Ordnerstruktur sollte also so aussehen:

config
  - .htaccess
  - CONFIG.php  
docker-compose.yml
Dockerfile

Wenn du nur den Webserver betreiben willst und schon einen extra Datenbank Server hast, reicht es aus, das Dockerfile zu bauen und zu starten. Einen evtl. vorhanden Proxyserver kannst du als Argument übergeben.

docker build --build-arg HTTP_PROXY=http://*server*:*port*/  .

Falls du auch noch einen Container mit der Datenbank darin brauchst, musst du die docker-compose Datei verwenden. Diese baut automatisiert beide Container.

Bitte beachte, dass du nach dem Start einmal ins Admin-Dashboard gehen und die Einstellungen speichern musst, damit alles reibungslos funktioniert.

version: "3"
services:
  mongo-db:
    image: 'mongo:5.0.0'
    container_name: osiris-db
    ports:
      - '27017:27017'
    volumes:
      - mongo_data:/data/db
  webserver:
    build:
      context: .
      dockerfile: ./Dockerfile
      args:
        PHP_VERSION: 81
        HTTP_PROXY: 'http://*server*:*port*'
    image: ifw/osiris
    container_name: osiris-app
    ports:
      - "80:80"
    depends_on:
      - mongo-db

volumes:
  mongo_data:
    driver: local

FROM php:8.1-apache

ARG HTTP_PROXY
ENV http_proxy ${HTTP_PROXY}
ENV https_proxy ${HTTP_PROXY}

# Apache rewrite Modul aktivieren 
RUN a2enmod rewrite

# benötigte Pakete installieren
RUN apt-get update \
    && apt-get install -qy --no-install-recommends \
        git \
        unzip \
        wget \
        zip \
        libzip-dev \
        libldap2-dev

# composer installieren
RUN curl 'https://getcomposer.org/installer' | php \
    && mv composer.phar /usr/local/bin/composer


# PHP Erweiterungen installieren
RUN pear config-set http_proxy ${HTTP_PROXY} \
    && pecl install mongodb \
    && cp /usr/local/etc/php/php.ini-production /usr/local/etc/php/php.ini \
    && echo "extension=mongodb.so" >> /usr/local/etc/php/php.ini \
    && docker-php-ext-install zip \
    && docker-php-ext-configure ldap --with-libdir=lib/x86_64-linux-gnu/ \
    && docker-php-ext-install ldap \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* 


# osiris von git laden 
RUN git clone https://github.com/JKoblitz/osiris.git /var/www/html

# Nutzerspzifische Dateien in Container kopieren
COPY config/.htaccess /var/www/html/.htaccess
COPY config/CONFIG.php /var/www/html/CONFIG.php

# php Libraries installieren
RUN cd /var/www/html && composer update

OSIRIS konfigurieren

Damit OSIRIS läuft müssen die wichtigen Einstellungen vorgenommen werden. Dazu muss die Datei CONFIG.default.php kopiert und in CONFIG.php umbenannt werden. In dieser Datei könnt ihr grundlegende Einstellungen anpassen, die nicht durch Updates überschrieben werden.

Datenbank-Verbindung

Die Datenbank-Verbindung muss ebenfalls in der CONFIG-Datei angegeben werden. Um gegebenenfalls Servereinstellungen und Nutzernamen angeben zu können, wird direkt der Verbindungsstring übergeben. Wenn ihr MongoDB mit den Standardeinstellungen in der gleichen VM installiert habt, sollten die Voreinstellungen funktionieren:

define("DB_NAME", "osiris");
define("DB_STRING", "mongodb://localhost:27017/" . DB_NAME . "?retryWrites=true&w=majority");

Mehr über die Verbindung mit dem Server könnt ihr direkt in der MongoDB-Dokumentation nachlesen.

Nutzerverwaltung

OSIRIS funktioniert zurzeit mit zwei unterschiedlichen Möglichkeiten der Nutzerverwaltung:

1. LDAP: über ein Active Directory werden die Nutzer zentral verwaltet und mittels LDAP-Authentifizierung werden die Daten an OSIRIS weitergegeben. Falls es euch möglich ist, solltet ihr diese Einstellung verwenden, da sie einerseits Arbeit spart (Nutzer müssen nicht manuell angelegt werden) und andererseits auch mehr Sicherheit bietet.
2. Auth-Addon: OSIRIS hat ein mitgeliefertes Addon zur Nutzer-Authentifizierung. Nutzer können sich dabei selbst einen Account erstellen.

Nutzerverwaltung mit LDAP

OSIRIS funktioniert zurzeit bevorzugt mit LDAP-Authentifizierung, die von den meisten Instituten zur Nutzerverwaltung verwendet wird.

Die LDAP-Einstellungen müssen ebenfalls in der Configuration angegeben werden. Falls ihr selbst nicht wisst, welche Einstellungen ihr vornehmen müsst, fragt am besten bei eurer IT nach.

define('USER_MANAGEMENT', 'LDAP');

define("LDAP_IP", "100.10.100.0");
define("LDAP_PORT", 389);
define("LDAP_USER", "osiris");
define("LDAP_DOMAIN", "@domain.local");
define("LDAP_PASSWORD", "ldap_password");
define("LDAP_BASEDN", "OU=Users,OU=DSMZ,DC=dsmz,DC=local");

Nutzerverwaltung mit Auth-Addon

Um die OSIRIS-eigene Nutzerauthentifizierung zu nutzen, muss nur folgende Einstellung in der CONFIG.php angepasst werden:

define('USER_MANAGEMENT', 'AUTH');

Die Nutzer-Authentifizierung findet jetzt über das OSIRIS-Addon statt. LDAP-Konfiguration muss demnach nicht vorgenommen werden.

Administrator_in

Die Variable ADMIN definiert den Nutzernamen des Administrators. Per Default kann dort nur ein Admin angegeben werden, dieser kann aber durch Bearbeitung eines Nutzerprofils anderen Nutzern ebenfalls Admin-Rechte geben.

Relativer Pfad

Die Variable ROOTPATH definiert, in welchem Unterordner euer Projekt wohnt. Sollte sich das Projekt wie oben angewiesen im Stammordner befinden, muss die Variable leer bleiben.

define('ROOTPATH', '/osiris');

RewriteBase /osiris

Troubleshooting

Für den Fall, dass etwas schief laufen sollte, sammle ich hier ein paar Tipps, die mir selbst oder anderen Nutzern schon weitergeholfen haben.

setsebool -P httpd_can_network_connect on

semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/(.*.json)"
restorecon -Rv /var/www/html

Optionale Workflows aktivieren

Workflows laufen regelmäßig und ermöglichen es, Arbeitsschritte zu automatisieren.

Generelles Setup

Für alle aktuellen (und vermutlich auch zukünftigen) Workflows wird Python 3 benötigt. Wie du Python am besten installierst, schaust du am besten in der offiziellen Dokumentation nach. Du wirst ebenfalls den Python-Paketinstallationsmanager pip benötigen.

Sobald Python 3 und pip installiert sind, kannst du mit folgendem Kommandozeilenbefehl den MongoDB-Connector installieren, der ebenfalls für alle Jobs benötigt wird:

pip install pymongo

Außerdem musst du die Konfigurationsdatei config.default.ini im jobs-Unterordner kopieren und die Kopie config.ini nennen (Dieses Vorgehen verhindert, dass deine Konfiguration durch OSIRIS-Updates überschrieben wird). In der Config-Datei müssen alle Variablen entsprechend angepasst werden, zum Beispiel die Informationen für die Datenbankverbindung.

Der Queue-Workflow

Der Queue-Workflow holt neue Aktivitäten aus Online-Quellen und speichert sie in einer Warteschlange. Die Benutzer werden benachrichtigt, wenn neue Aktivitäten in der Warteschlange warten, und können sie einfach zu OSIRIS hinzufügen.

Vorbereitung

Zur Vorbereitung dieses Workflows müssen zunächst drei weitere Python-Pakete installiert werden. Dies geschieht erneut mit pip:

pip install diophila
pip install nameparser
pip install levenshtein

Zusätzlich musst du die OpenAlex-ID Ihres Instituts in der Datei config.ini ändern. Um diese ID zu finden, suchst du dein Institut am besten auf der Webseite von OpenAlex. Die ID findest du entweder als letztem Teil der URL oder unter Identifiers > openalex. Sie beginnt mit einem I, gefolgt von einer Reihe von Zahlen. Sie muss in der config.ini eingetragen werden:

[OpenAlex]
Institution = I7935750

Außerdem von Relevanz ist das StartYear, von dem an Aktivitäten importiert werden, sowie die AdminMail, mit derer die Abfragen bei OpenAlex getätigt werden.

Den Cron-Job anlegen

Zu guter Letzt können wir den Cron-Job anlegen. Ein Cron-Job ist ein geplanter, sich wiederholender Vorgang, den ein System zu einer festgelegten Zeit durchführt. Die folgenden Einstellungen bedeuten, dass der Workflow einmal pro Woche durchgeführt wird, genauer gesagt jeden Sonntag um 2 Uhr morgens. Wir benutzen den Editor nano für diese Aktion, ihr könnt aber natürlich auch jeden anderen Editor verwenden.

EDITOR=nano crontab -e 

# enter this as cronjob:
0 2 * * 0 python3 /var/www/html/jobs/openalex_parser.py

# press Ctrl+O to save and Ctrl+X to exit

Die Ausgabe sollte euch zeigen, dass ein neuer Cron-Job installiert wurde. Im folgenden werden jeden Sonntag neue Publikationen zu euer Warteliste hinzugefügt.

Altdaten importieren

Variante 1: Altdaten automatisch über OpenAlex importieren

Es ist möglich, ohne großen Aufwand Altdaten in OSIRIS zu importieren. Um OSIRIS auf den Import vorzubereiten, müssen jedoch erst ein paar Installationsschritte und Konfigurationen durchgeführt werden. Am besten haltet ihr euch dafür an die Anleitung zur Einrichtung der Workflows. Ihr müsst dabei das generelle Setup sowie die Vorbereitung des Queue-Workflows abarbeiten (inklusive der Konfiguration), bis zu dem Punkt, an dem steht, dass ihr bereit für den Altdaten-Import seid. Dann kehrt hierher zurück, um mit dem Import der Altdaten fortzufahren.

Mit dem folgenden Script werden alle Altdaten aus OpenAlex direkt in eure Datenbank importiert. Warum das eine tolle Idee ist, lest ihr am besten hier. Das Script zum Import der Altdaten wird mit folgendem Aufruf gestartet:

python jobs/import_data.py

Wenn das Skript erfolgreich ausgeführt wurde, dann müssten jetzt DOIs erscheinen, die nacheinander in die Datenbank eingepflegt werden. Je nachdem, wie viele Altdaten importiert werden, kann dieser Prozess eine ganze Weile dauern.

Variante 2: Altdaten über eine Liste von DOIs importieren

Ihr könnt auch eine Liste von DOIs nutzen, um schnell viele Daten in OSIRIS zu importieren. Dazu habe ich euch ein Python-Skript vorbereitet, dass ihr ebenfalls im Ordner Jobs findet (erst ab dem 5. März 2024).

Ihr führt dazu folgende Schritte durch:

1. Ihr tragt alle DOIs, die ihr gern importieren wollt, in eine CSV-Datei ein, eine DOI pro Zeile. Am besten ohne URL, geht aber wohl auch mit. Ich habe euch auch schon eine Beispieldatei mit in den Ordner gepackt.
2. Falls eure Datei anders heißt oder woanders gespeichert ist, müsst ihr den Pfad in der import_doi.py anpassen.
3. Das wars eigentlich auch schon. Jetzt nur noch folgenden Befehl in der Kommandozeile ausführen und ab geht die Post:

   python jobs/import_doi.py

Durchstarten

Herzlichen Glückwunsch. Wenn alles geklappt hat, könnt ihr jetzt mit OSIRIS durchstarten. Geht auf die Webseite des Servers, den ihr euch eingerichtet habt. Hier solltet ihr nun eine Anmeldemaske sehen. Wenn ihr die Verknüpfung zum Active Directory eingerichtet habt, könnt ihr euch hier mit eurem Windows-Account anmelden. Da OSIRIS euch noch nicht in der (noch leeren) Datenbank finden wird, wird er automatisch einen Account für euch anlegen. Die Nutzerdaten zieht er sich dabei aus eurer Nutzerverwaltung.

Die Datenbank ist im Moment noch leer, doch ihr könnt sie einfach über die Weboberfläche füllen. Weitere Nutzer fügt ihr hinzu, sobald sie sich das erste Mal angemeldet haben. Ich arbeite im Moment noch an einem Init mit einem Vollimport, das wird aber eventuell noch etwas dauern.