subkom Wissensdatenbank – Übersicht

Docs: Smartbib Installation mit HELM

Mon, 01 Jan 0001 00:00:00 +0000

Einleitung

Dieses Tutorial dient als Step-by-Step Anleitung und zeigt wie man Smartbib in einer Kubernetes Umgebung installieren kann.

Für die Installationanleitung wird MicroK8s von Canonical verwendet. https://microk8s.io/

SNAP installieren

Für die generelle Installation ist snap (https://snapcraft.io/) erforderlich, da microk8s über den Snap Store verfügbar ist.

In den meisten Ubuntu-basierten Distributionen ist der snapd Daemon bereits vorinstalliert.

Falls man andere Distributionen verwenden möchte, dann findet man unter https://snapcraft.io/docs/installing-snapd die notwendigen Installationsschritte.

So gibt es z.B. snapd ab Debian 9 (Strech) bereits als APT Package.

$ sudo apt install snapd

Microk8s

Micro Kubernetes installieren

Es kann nun microk8s in der aktuellen Version mit Hilfe von Snap über installiert werden.

$ sudo snap install microk8s --classic

Alternativ: Version festlegen

Sollte man eine spezielle Kubernetes Version verwenden wollen, so kann man dies alternativ über die Angabe des Channels festlegten.

$ sudo snap install microk8s --classic --channel=1.19/stable

Die verfügbaren Channels kann man sich mit snap info microk8s anzeigen lassen.

Berechtigungen für aktuellen User setzen

Wenn man nicht mit sudo sondern direkt mit dem aktuellen Benutzer einen Zugriff auf die kubernetes Installation haben möchte, dann empfiehlt sich eine Anpassung der Benutzerberechtigungen.

Folgender Befehl gibt dem aktuellen User die erforderliche Gruppenberechtigung.

$ sudo usermod -a -G microk8s $USER

Alias setzen

Grundsätzlich sind nun alle kubernetes Commands per microk8s. Prefix über die Shell verfügbar. (z.B. microk8s.kubectl)

Bei häufig genutzen Commands - wie dies bei kubectl meist der Fall ist - empfiehlt es sich, dass man Shell Aliase setzt.

Hier ein Beispiel, falls man BASH verwendet:

$ echo "alias kubectl='microk8s.kubectl'" >> ~/.bash_aliases
$ echo "alias helm='microk8s.helm'" >> ~/.bash_aliases

Nach der Neuanmeldung stehen dann die Aliase zur Verfügung.

$ su - $USER

Microk8s Module installieren

Nun können erforderliche MicroK8s Module aktiviert werden.

Für die Smartbib-Installation werden folgende Module benötigt:

dns: CoreDNS (verwendet als Default 8.8.8.8 u.w. als Upstream DNS)
storage: Dateipfade des Hosts werden als Storage zur Verfügung gestellt
ingress: NGINX Ingress Controller (für Namesbaisertes Virtual Hosting)

Die Module können mit folgendem Befehl installiert werden:

$ microk8s.enable dns storage ingress

HELM- und Docker-Repository

Um das Deployment von Smartbib zu vereinfachen wird der Package Manager helm (https://helm.sh/) verwendet.

Wir stellen für Smartbib ein helm und docker-repository zur Verfügung:

docker: https://registry.smartbib.net
helm: https://registry.smartbib.net/charts/

Für den Zugriff benötigen Sie einen Benutzernamen und ein Passwort.
Bei folgenden Anleitungen werden hierfür die Environment-Variablen $USERNAME und $PASSWORD verwendet.

HELM Package Manager installieren

Der aktuelle HELM Package Manger kann per microk8s.enable oder SNAP installiert werden.
Die integrierte Version in microk8s ist jedoch meist etwas veraltet.
Aus diesem Grund wird die Installation mit snap gewählt:

$ sudo snap install helm --classic

Damit der HELM Package Manager - ohne weitere Konfiguration - Zugriff auf die MicroK8s Installation erhält, kann ein symbolischer Link in der microk8s-Installlation angelegt werden.

$ sudo mkdir -p /var/snap/microk8s/current/bin
$ sudo ln -s /snap/bin/helm /var/snap/microk8s/current/bin/helm

Smartbib Helm Repository hinzufügen

Ihre Zugangsdaten müssen sich in den Environment-Variablen $USERNAME und $PASSWORD befinden.

Hinzufügen das Smartbib HELM Repositories:

$ helm repo add smartbib https://registry.smartbib.net/charts/ --username $USERNAME --password $PASSWORD
$ helm repo update

Das Helm Respostory kann nun kurz mit folgendem Befehl geprüft werden:

$ helm search repo

Docker Repositiory Credentials setzen

$ kubectl create secret docker-registry regcred --docker-server=registry.smartbib.net --docker-username=$USERNAME --docker-password=$PASSWORD

Optional: Cert-Manager installieren

Um die Ausstellung von Zertifikaten zu vereinfachen, kann für Kubernetes der Cert-Manager (https://cert-manager.io) verwendet werden.

Im folgenden Beispiel wird der Cert-Manager mit Hilfe des HELM Package Managers installiert und es werden Issuer für Letscrypt-Zertikatsausstellungen (production und staging) angelegt.
Es wird dabei der HTTP Solver verwendet.

Nach Abschluss wird es dann möglich sein, dass die automatische Zertifkatserstellung direkt per Annotation bei der Ingress Definition hinterlegt werden kann.

Helm Repository hinzufügen

Der Cert-Manager kann sehr einfach über HELM depolyed werden.
Als erster Schritt muss hierfür das Jetstack HELM-Repository hinzugefügt werden:

$ helm repo add jetstack https://charts.jetstack.io
$ helm repo update

Cert-Manager mit HELM installieren

Nun kann der Cert-Manager bereit gestellt werden.
Es bietet sich hier die Verwendung eines eigenen Namespaces (z.B. cert-manager) an.

$ kubectl create namespace cert-manager
$ helm install cert-manager jetstack/cert-manager --namespace cert-manager --version v1.1.0 --set installCRDs=true

Create Letsencrypt Certificate Issuers

Es werden nun die Issuer für die Zertifikat-Requests erstellt.
Es wird ein ClusterIssuer verwendet, der namespace-übergreifend funktioniert, aber die Verwendung des Issuer ist genauso möglich.
Im Folgenden werden 2 neue YAML Dateien angelegt, die für Production und für Staging-Requests genutzt werden können.

Die Email-Adresse muss entsprechend angepasst werden.
Im Beispiel wird ein HTTP Challenge Solver verwendet.

Production

letsencrypt-cluster-issuer.yaml

apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
 name: letsencrypt
spec:
 acme:
 # You must replace this email address with your own.
 # Let's Encrypt will use this to contact you about expiring
 # certificates, and issues related to your account.
 email: email@example.com
 server: https://acme-v02.api.letsencrypt.org/directory
 privateKeySecretRef:
 # Secret resource that will be used to store the account's private key.
 name: letsencrypt-account-key
 # Add a single challenge solver, HTTP01 using nginx
 solvers:
 - http01:
 ingress:
 class: nginx

Staging

letsencrypt-staging-cluster-issuer.yaml:

apiVersion: cert-manager.io/v1alpha2
kind: ClusterIssuer
metadata:
 name: letsencrypt-staging
spec:
 acme:
 email: email@example.com
 server: https://acme-staging-v02.api.letsencrypt.org/directory
 privateKeySecretRef:
 name: letsencrypt-staging-account-key
 solvers:
 - http01:
 ingress:
 class: nginx

Letencrypt Issuers

Nun können die 2 Issuers mit Hilfe von kubectl apply hinzugefügt werden.

$ kubectl apply -f letsencrypt-cluster-issuer.yaml
$ kubectl apply -f letsencrypt-staging-cluster-issuer.yaml

Verwenden der Issuer

Nun können die Issuer in den Annotations der Ingress Konfguration verwendet werden:

ingress:
 ...
 annotations:
 cert-manager.io/cluster-issuer: letsencrypt

oder

ingress:
 ...
 annotations:
 cert-manager.io/cluster-issuer: letsencrypt-staging

YAML Konfiguration für HELM erzeugen

Nun muss eine HELM Konfiguration erstellt werden oder sie erhalten eine vorkonfigurierte Datei.

Im folgenden Texten und Dateiausschnitten wird der Begriff CUSTOMER_TOKEN verwendet.
An all diesen Stellen sollten sie ihr eigenes TOKEN angeben, dass sie von uns erhalten haben.

CUSTOMER_TOKEN.yaml:

# Wichtig: Token setzen
customer: CUSTOMER_TOKEN 

solr:
 keep: true # Solr Index auch beim Löschen des Charts behalten

# Ingress für namebased virtual hosting und Letscrypt Certificate Requests
ingress:
 enabled: true
 annotations:
 cert-manager.io/cluster-issuer: letsencrypt
 hosts:
 - host: smartbib.example.com
 paths: [""]
 tls:
 - secretName: smartbib.example.com
 hosts:
 - smartbib.example.com

# Optional: BibConnector Konfigurationen
bibcon:
 enabled: true
 configFiles:
 data:
 bibConnector.xml: |-
 <configuration>
 <bibConnector>BIBL</bibConnector>
 ...
 <port>8040</port>
 </configuration>
 BIBL.xml: |-
 <configuration>
 ...
 </configuration>

Nur HTTP Ingress verwenden

Falls der Cert-Manager nicht verwendet wird und die Zertifikatsausstellung an anderer Stelle, z.B. durch einen Proxy erledigt wird, dann ist es möglich, dass man die automatische HTTP -> HTTPS Weiterleitung deaktivieren kann.
Hierfür muss eine Annotation hinzugefügt werden: nginx.ingress.kubernetes.io/ssl-redirect: "false".
Auf den Block tls kann nun komplett verzichtet werden.

Beispiel:

...

# Ingress für namebased virtual hosting und Letscrypt Certificate Requests
ingress:
 enabled: true
 annotations:
 nginx.ingress.kubernetes.io/ssl-redirect: "false"
 hosts:
 - host: smartbib.example.com
 paths: [""]
...

Smartbib starten

$ helm install smartbib-CUSTOMER_TOKEN smartbib/smartbib -f CUSTOMER_TOKEN.yaml

Installation prüfen

Zuerst sollte man warten bis alle Pods gestartet wurden:

$ kubectl get pods -w

(Abbruch mit Strg+C)

Zugriff auf die Logs

ENV Variable erstellen

Im ersten Schritt ist es hilfreich, dass man eine Environment Variable erstellt, damit man den HASH des Pods nicht per Hand eingeben muss:

$ export SMARTBIB_POD=$(microk8s.kubectl get pods --namespace default -l "app.kubernetes.io/name=smartbib,app.kubernetes.io/instance=smartbib-CUSTOMER_TOKEN" -o jsonpath="{.items[0].metadata.name}")

(smartbib-CUSTOMER_TOKEN muss entsprechend angepasst werden)

Logs anzeigen/verfolgen

Hier ein Bespiel wie man z.b die BibConnector-Ausgabe einsehen kann:

$ kubectl logs $SMARTBIB_POD -c bibcon -f

Eine komplette Liste aller Möglichkeiten erhält man, wenn man den -c Parameter weglässt:

$ kubectl logs $SMARTBIB_POD

Docs: Smartbib Installation unter SuSE Linux Enterprise

Mon, 01 Jan 0001 00:00:00 +0000

Einleitung

Dieses Tutorial zeigt wie man Smartbib unter SuSE Linux Enterprise installieren kann.

Diese Methode bietet sich für alle Installationen an, bei denen keine Container genutzt werden oder nur ein beschränkter Internet-Zugang verfügbar ist.

Basis-Installation SuSE

Für diese Dokumentation wurde SLES 15 SP 2 in einer Oracle VirtualBox VM installiert. (https://www.suse.com/download/sles/)

Es wurde bei der Erstellung darauf Wert gelegt, dass nach Möglichkeit nur das offizielle Installations-Medium für die notwendigen SuSE Package verwendet wird und für den kompletten Installations-Vorgang keine Internet-Verbindung erforderlich ist.

Installierte SuSE Module

Basesystem
Development Tools
Server Applications
Web and Scripting

SuSE Firewall-Einstellungen

firewall-cmd --permanent --add-service=ssh
firewall-cmd --permanent --zone=public --add-service=http
firewall-cmd --permanent --zone=public --add-port=8983/tcp
firewall-cmd --permanent --reload
firewall-cmd --permanent --list-all

Smartbib Benutzer anlegen

groupadd smartbib
useradd -G smartbib smartbib

SuSE Pakete installieren

Für die Installation der SuSE Pakete wurde zypper verwendet:

Java installieren

zypper in java-11-openjdk

MariaDB installieren und aktivieren

MariaDB mit Hilfe von zypper installieren

zypper in mariadb

Den Systemd Service aktivieren und starten

systemctl enable mariadb
systemctl start mariadb

Für die aktuelle Smartbib-Installation ist es notwendig, dass die Socket-Authentification deaktivert wird und stattdessen ein Root-Passwort gesetzt wird. Die kann mit Hilfe von mysql_secure_installation vorgenommen werden:

mysql_secure_installation

Apache2 mit PHP und weitere Pakete

zypper in zip apache2 yast2-http-server apache2-mod_php7 php7-mbstring php7-pear php7 php7-devel php7-gd php7-intl php7-json php7-ldap php7-mysql php7-curl php7-xmlreader php7-xmlrpc php7-xmlwriter php7-soap php7-curl php7-xsl php7-zlib

Über yast kann der Apache2 konfiguriert werden: Netzwerkdienste -> HTTP-Server

yast

Es können generell alle Standardeinstellungen verwendet werden, da weitere Einstellungen über die Konsole durchgeführt werden.

Notwendige Einstelungen über YaST: Der Firewall-Port sollte geöffnet werden und PHP muss generell aktiviert werden.

Apache Module aktivieren: Rewrite und Env

Es ist notwendig, die Apache-Module rewrite und env zu aktivieren:

a2enmod rewrite
a2enmod env
systemctl restart apache2

Smartbib Installation

Alle notwendigen Dateien für Smartbib werden mit TAR-Paketen bereitgestellt:

Beispiele:

smartbib-drv-complete-with-config-7.1.0.tar.gz
smartbib-drv-complete-7.1.0.tar.gz

Für die erste Installation sollte das Paket -with-config- verwendet werden, da hier schon vorgefertigte Kunden-Konfgurationen enhalten sind.

Entpacken nach /usr/local/smartbib

Das bereitgestellte Archiv sollte im /usr/local/ Verzeichnis entpackt werden:

tar -xz -C /usr/local/ -f smartbib-drv-complete-with-config-7.1.0-beta.tar.gz

MariaDB Tabelle anlegen

Mit folgendem SQL Skript wird eine neue Datenbank smartbib und ein Benutzer smartbib erstellt. Es werden auch alle notwendigen Tabellen erstellt.

mysql < /usr/local/smartbib/setup/setup-smartbib.sql

Es werden bereits vordefinierte Passwörter gesetzt und sind in entsprechende Smartbib INI Dateien eingetragen. Falls ein andere Passwort verwendet wird, dann muss dies auch in der Datei /usr/local/smartbib/vufind/local/config/vufind/config.ini angepasst werden.

Record-Manager Tabelle anlegen

Für den Daten-Import bei Verbund-System kommt der RecordManager zu Einsatz, damit eine Dubletten-Erkennung stattfindet.

Der RecordManager kann dabei entweder MongoDB oder MySQL/MariaDB verwenden.
Da keine offiziellen SuSE Pakete für MongoDB bereitstehen, die offline installiert wird bei SuSE-Linux die MariaDB-Variante verwendet.

Die notwendige Tabellenstruktur kann mit folgendem SQL Skript erstellt werden:

mysql < /usr/local/smartbib/setup/setup-recman.sql

Es werden bereits vordefinierte Passwörter gesetzt und sind in entsprechende RecordManager INI Dateien eingetragen. Falls ein anderes Passwort verwendet wird, dann muss dies auch in der Datei /usr/local/smartbib/recordmanager/conf/recordmanager.ini angepasst werden.

Setup starten

Es existert ein Setup-Shell-Skript, dass die restlichen Anpassungen vornimmt.

Dazu zählen die Dateiberechtigungen, das Anlegen der Log-Verzeichnisse, das Starten von Systemd-Services und Timern und das Aktivieren unter Apache2.

cd /usr/local/smartbib/setup/
./setup.sh

Sollte dieses automatische Vorgehen eher unerwünscht sein, dann können diese Schritte auch alternativ einzeln anhand der folgenden Anweisungen durchgeführt werden.

Alternativ: Manuelles Setup

Die folgenden Anweisungen müssen nur durchgeführt werden, wenn auf die Anwendung von setup.sh verzichtet wird!

Zugriffsrechte setzen

chown -R smartbib:smartbib /usr/local/smartbib
chown -R wwwrun:smartbib /usr/local/smartbib/vufind/local/cache
chown -R wwwrun:smartbib /usr/local/smartbib/vufind/local/config
mkdir /usr/local/smartbib/vufind/local/cache/cli
chmod 777 /usr/local/smartbib/vufind/local/cache/cli

Log-Verzeichnis erstellen

mkdir -p /var/log/smartbib/
chown -R wwwrun:smartbib /var/log/smartbib/
chmod g+w /var/log/smartbib/

Smartbib/SOLR Systemd Service aktivieren und starten

systemctl enable /usr/local/smartbib/service/smartbib-solr.service
systemctl start smartbib-solr.service

Systemd Timer für Converter, Importer und Indexgenerierung

systemctl enable /usr/local/smartbib/service/smartbib-convert.service
systemctl enable /usr/local/smartbib/service/smartbib-convert.timer
systemctl start smartbib-convert.timer
systemctl enable /usr/local/smartbib/service/smartbib-import.service
systemctl enable /usr/local/smartbib/service/smartbib-import.timer
systemctl start smartbib-import.timer
systemctl enable /usr/local/smartbib/service/smartbib-index-browse.service
systemctl enable /usr/local/smartbib/service/smartbib-index-browse.timer
systemctl start smartbib-index-browse.timer

Apache konfigurieren

ln -s /usr/local/smartbib/service/httpd-smartbib.conf /etc/apache2/conf.d/smartbib.conf
systemctl restart apache2

Daten importieren

Die Daten-Dateien müssen im Verzeichnis /usr/local/smartbib/import-data/upload/ abgelegt werden und werden dann mit Hilfe von Systemd-Timern verarbeitet. Der Benutzer smartbib muss Lese- und Schreibrechte für diese Datei besitzen. Die Daten werden dann nachts automatisch verarbeitet.

Die Liste der Timer kann man sich mit systemctl anzeigen lassen:

systemctl list-timers

Möchte man schon vorher die Vorgänge starten, kann man dies mit Hilfe der hinterlegten Systemd-Services erledigen.

# Konvertierung
systemctl start smartbib-convert
# Dubletten-Erkennung + SOLR Import
systemctl start smartbib-import
# Erstellen des alphabetischen Suche-Index
systemctl start smartbib-index-browse

Mit entsprechenden journalctl Aufrufen können die Vorgänge geprüft werden.

Beispiel: Verfolgen des aktuell laufenden Imports:

journalctl -u smartbib-import -f

Log-Dateien überprüfen

Im Verzeichnis /var/log/smartbib/ befinden sich alle Log-Dateien.

Neben generellen Smartbib PHP Logs und SOLR-Log-Dateien findet man hier auch die Log-Dateien der Konvertierungen (convert/) und Import-Vorgänge (recman).

Weitere Konfigurationen

Weitere Konfigurationen müssen dann entsprechend der Anforderungen vorgenommen werden und finden sich in der Regel im /usr/local/smartbib/vufind/local/config/vufind/ Verzeichnis.

Die E-Mail-Konfiguration ist Standardmäßig auf localhost eingestellt und wird dadurch durch einen lokal installierten Postfix-Service entgegengenommen. Andere E-Mail-Einstellungen können auch direkt über die config.ini vorgenommen werden.

Die vorliegende Anleitung soll nur als grobe Struktur für die Installation dienen.