Installation von OSIRIS
Disclaimer
Diese Anleitung ist noch nicht auf vielen Systemen getestet worden. Feedback ist daher sehr willkommen.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 zu installieren. OSRIS wurde mit den Versionen 5, 6 und 7 getestet.
sudo yum install -y mongodb-org
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 -y install gcc php-pear php-devel php-ldap
sudo pecl install mongodb
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
# dann:
composer update
Falls es bei euch nicht klappt, versucht mal --ignore-platform-reqs
zu allen Aufrufen hinzuzufügen
.htaccess
Damit OSIRIS vernünftig funktioniert, muss die.htaccess
-Datei im OSIRIS-Ordner existieren werden.
Ab Version 1.3.6 wird die Datei mit Git mitgeliefert.
Falls ihr OSIRIS in einem Unterordner installieren wollt, müsst ihr die .htaccess
-Datei anpassen und den RewriteBase
ändern.
Vergesst nicht, den ROOTPATH
in der CONFIG anzupassen wie weiter unten beschrieben und die Datei dann durch Aktualisierung durch Git zu schützen:
git update-index --skip-worktree .htaccess
Als Referenz könnt ihr hier die .htaccess
-Datei von OSIRIS sehen:
DirectoryIndex index.php
# enable apache rewrite engine
RewriteEngine on
# set your rewrite base, change this if you are running in a subdirectory
RewriteBase /
# Deliver the folder or file directly if it exists on the server
RewriteRule ^(css|img|js|uploads|settings.json|manifest.json)($|/) - [L]
# Push every request to index.php
RewriteRule ^(.*)$ index.php [QSA]
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.
Benötigte Programme
Anleitung
- 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. - Die MongoDB Datenbank als .msi runterladen und installieren. Die aktuellste Version (6.0) ist kompatibel mit OSIRIS. Im Installationsmenü alle Voreinstellungen so lassen.
- 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. - 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. - 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 Befehlcd
. Wenn Xampp standardmäßig installiert ist lautet der Befehlcd C:\xampp\htdocs
Wenn man sich jetzt im Verzeichnis befindet, gibt manComposer update
ein. Wenn alles funktioniert, lädt Composer die fehlenden libraries nach. - Wenn nicht bereits geschehen, XAMPP starten und bei Apache auf „Start“ bzw. „Restart“ klicken. In den Browser localhost eingeben und die Webseite sollte erscheinen.
- 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:
- 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.
- 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.
Migration der Nutzerverwaltung
Sowohl LDAP als auch das Auth-Addon kümmern sich um die Authentifizierung der Nutzer. Bei LDAP werden grundlegende Nutzerdaten ebenfalls aus dem Active Directory synchronisiert, beim Auth müssen diese vom Nutzer bei der Registrierung angelegt werden. Die eigentlichen Nutzerdaten werden aber immer in OSIRIS gespeichert. Das führt dazu, dass sich im Nachhinein leicht von Auth auf LDAP migriert werden kann. Dabei muss nur beachtet werden, dass die Nutzernamen mit denen im LDAP identisch sind. Dadurch weiß das System später noch, welcher Nutzer zu welchem Account gehört.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.
OSIRIS in einem Unterordner
Wenn euer Projekt in einem Unterordner angelegt werden soll, müsst ihr diese Information an zwei stellen verändern. Nehmen wir im folgenden Beispiel mal an, das System wird im Unterordner osiris
installiert. Einmal müsst ihr in der CONFIG.php
die folgende Zeile anpassen:
define('ROOTPATH', '/osiris');
Außerdem müsst ihr den Pfad auch in der .htaccess
-Datei anpassen:
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.
Anscheinend kann OSIRIS keine Verbindung zu MongoDB aufbauen. Ich bekomme den Fehler No suitable servers found
.
setsebool -P httpd_can_network_connect on
Ich kann die Einstellungen im Admin-Dashboard nicht speichern bzw. nach dem Speichern werden sie zurückgesetzt.
settings.json
-Datei zu schreiben.
Ich habe mich am Ende durch diese fantastische Antwort auf StackOverflow gearbeitet, nur um zu bemerken, dass auch hier wieder SELinux seine Finger im Spiel hatte (Corner case #2). Schaut es euch an und arbeitet es ab, mir haben folgende Zeilen Code geholfen:
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:
- 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.
-
Falls eure Datei anders heißt oder woanders gespeichert ist, müsst ihr den Pfad in der
import_doi.py
anpassen. -
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
Standardmäßig wird auch mittels Levenshtein-Ähnlichkeit nach übereinstimmenden Titeln (mehr als 90% Übereinstimmung) gefiltert. Falls das nicht gewünscht ist, müsst ihr in der
import_doi.py
den Wert ignoreDupl
auf False
setzen.
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.