3.2 Docker

Einleitung

Die folgende Installationsanleitung für den Goobi viewer bezieht sich auf Ubuntu Linux 20.04. Sie ist als Schritt für Schritt Anleitung von oben nach unten geschrieben, das bedeutet, dass Einstellungen und Konfigurationen aufeinander aufbauen. Wird die Reihenfolge nicht eingehalten, können unter Umständen bestimmte Befehle fehlschlagen.

Als Domainname wird in dieser Anleitung VIEWER.EXAMPLE.ORG verwendet, dies bitte an den eigenen DNS Namen anpassen.

Für den Einsatz wird eine virtuelle Maschine mit mindestens 4 CPUs und 8GB RAM empfohlen. Für den produktiven Einsatz werden 8 CPUs und 16GB RAM empfohlen.

Befehle aus dieser Anleitung werden am besten mit einem Klick auf das entsprechende Icon kopiert. Andernfalls besteht die Gefahr ungewollte Whitespaces mit zu kopieren

Vorbereitung

Zuerst auf dem Server, auf dem der Goobi viewer installiert werden soll, anmelden und root Rechte erlangen:

ssh VIEWER.EXAMPLE.ORG
sudo -i

Anschließend ein Passwort für die Goobi viewer Datenbank und einen Token generieren und als Variable in der Session ablegen. Dort wird ebenfalls der DNS Name hinterlegt:

export VIEWER_HOSTNAME=VIEWER.EXAMPLE.ORG
export PW_SQL_ROOT=SECRETROOTPASSWORD
export PW_SQL_VIEWER=SECRETPASSWORD
export VIEWER_USERNAME=[e-mail]
export VIEWER_USERPASS=SECRETPASSWORD
export VIEWER_IMAGE=intranda/goobi-viewer-theme-reference:develop
export VIEWER_THEME=reference
export TOKEN=$(uuidgen)

Nun die folgenden Pakete installieren:

apt -y install docker.io docker-compose mariadb-client python3-passlib python3-bcrypt

Es empfiehlt sich zum jetzigen Zeitpunkt einen DNS Eintrag für den Server gesetzt zu haben.

Verzeichnisstruktur erstellen

Mit den folgenden Befehlen wird die erforderliche Ordnerstruktur erzeugt:

mkdir -p /opt/digiverso/{indexer,logs,viewer/{abbyy,cmdi,db,deleted_mets,dev,hotfolder,media,orig_lido,orig_denkxweb,success,ugc,alto,cms_media,error_mets,indexed_lido,mix,pdf,tei,updated_mets,cache,config/{PDFTitlePage,watermark,docker},fulltext,indexed_mets,oai/token,ptif,themes,wc}}
mkdir -p /opt/digiverso/zookeeper/{data,datalog}/
mkdir -p /opt/digiverso/solr/data/solr
sudo chown -R 8983:8983 /opt/digiverso/solr

Konfigurationsdateien

Bevor die Container gestartet werden, müssen im Dateisystem die Verzeichnisse und Konfigurationsdateien für den Produktivbetrieb vorliegen.

config_viewer.xml

In der lokalen config_viewer.xml müssen verschiedene Einstellungen hinterlegt werden, hierbei muss gegebenenfalls das Protokoll angepasst werden:

sed -e "s|VIEWER.EXAMPLE.ORG|${VIEWER_HOSTNAME}/viewer|g" -e "s|TOKEN|${TOKEN}|g" -e "s|VIEWERTHEME|${VIEWER_THEME}|g" << "EOF" >/opt/digiverso/viewer/config/config_viewer.xml
<?xml version="1.0" encoding="UTF-8" ?>
<config>
        <urls>
                <metadata>
                        <sourcefile>https://VIEWER.EXAMPLE.ORG/sourcefile?id=</sourcefile>
                        <marc>https://VIEWER.EXAMPLE.ORG/oai?verb=GetRecord&amp;metadataPrefix=marcxml&amp;identifier=</marc>
                        <dc>https://VIEWER.EXAMPLE.ORG/oai?verb=GetRecord&amp;metadataPrefix=oai_dc&amp;identifier=</dc>
                        <ese>https://VIEWER.EXAMPLE.ORG/oai?verb=GetRecord&amp;metadataPrefix=europeana&amp;identifier=</ese>
                </metadata>

                <download>https://VIEWER.EXAMPLE.ORG/download/</download>
                <rest>https://VIEWER.EXAMPLE.ORG/api/v1/</rest>
        </urls>

        <viewer>
                <theme mainTheme="VIEWERTHEME" discriminatorField="" />
        </viewer>

        <rss>
                <numberOfItems>50</numberOfItems>
                <title>Goobi viewer RSS Feed</title>
                <description>new items</description>
                <copyright>(c) Goobi viewer using institution </copyright>
        </rss>

        <webapi>        
                <authorization>
                        <token>TOKEN</token>
                </authorization>
        </webapi>
</config>
EOF

config_oai.xml

Auch eine lokale config_oai.xml wird benötigt:

sed -e "s|VIEWER.EXAMPLE.ORG|${VIEWER_HOSTNAME}|g" << "EOF" >/opt/digiverso/viewer/config/config_oai.xml
<?xml version="1.0" encoding="UTF-8"?>
<config>
        <identifyTags>
                <baseURL useInRequestElement="true">https://VIEWER.EXAMPLE.ORG/viewer/oai</baseURL>
                <adminEmail>[e-mail]</adminEmail>
        </identifyTags>
        <urnResolverUrl>https://VIEWER.EXAMPLE.ORG/viewer/resolver?urn=</urnResolverUrl>
        <piResolverUrl>https://VIEWER.EXAMPLE.ORG/viewer/piresolver?id=</piResolverUrl>
</config>
EOF

XSL Dateien

Die OAI Schnittstelle des Goobi viewers benötigt zwei weitere Dateien:

wget -O /opt/digiverso/viewer/oai/MARC21slimUtils.xsl.xml https://raw.githubusercontent.com/intranda/goobi-viewer-connector/master/goobi-viewer-connector/src/main/resources/MARC21slimUtils.xsl
wget -O /opt/digiverso/viewer/oai/MODS2MARC21slim.xsl https://raw.githubusercontent.com/intranda/goobi-viewer-connector/master/goobi-viewer-connector/src/main/resources/MODS2MARC21slim.xsl

Für den Sourcefile Resolver wird die XSL Datei benötigt, die die METS fileGrp PRESENTATION sowie Zugriffsbeschränke Metadaten herausfiltert:

wget -O /opt/digiverso/viewer/config/METS_filter.xsl https://raw.githubusercontent.com/intranda/goobi-viewer-core-config/refs/heads/master/goobi-viewer-core-config/src/main/resources/install/METS_filter.xsl

config_indexer.xml

Die folgenden Befehle ausführen um die aktuelle config_indexer.xml herunterzuladen und entsprechend anzupassen:

wget -O /opt/digiverso/indexer/config_indexer.xml https://raw.githubusercontent.com/intranda/goobi-viewer-indexer/master/goobi-viewer-indexer/src/main/resources/config_indexer.xml
sed -e 's|<solrUrl>.*</solrUrl>|<solrUrl>http://solr:8983/solr/collection1</solrUrl>|' -e 's|C:/|/|g' -e "s|<viewerUrl>.*</viewerUrl>|<viewerUrl>https://${VIEWER_HOSTNAME}/viewer/</viewerUrl>|" -i /opt/digiverso/indexer/config_indexer.xml

Cronjob

Für regelmäßige Aufgaben müssen Cronjobs eingerichtet werden:

sed -e "s|VIEWER.EXAMPLE.ORG|${VIEWER_HOSTNAME}|g" -e "s|TOKEN|${TOKEN}|g" << "EOF" >/etc/cron.d/intranda-goobiviewer
PATH=/usr/bin:/bin:/usr/sbin/
MAILTO=[e-mail]

#
# Regular cron jobs for the Goobi viewer
#

## Optimize the Solr search index once a month
@monthly            root    curl -s 'http://solr/solr/collection1/update?optimize=true&waitFlush=false'
EOF

ACHTUNG: Wenn die Installation nicht über HTTPS zur Verfügung steht, dann müssen an dieser Stelle die soeben angelegten Dateien geöffnet und das Schema manuell angepasst werden.

my.cnf

Für den einfacheren Zugriff auf die Datenbank später, wird für den Benutzer root eine my.cnf mit den entsprechenden Zugangsdaten abgelegt:

test -e /root/.my.cnf && echo 'WARNING, .my.cnf already exists!' ||
echo -e "[client]\nhost=127.0.0.1\npassword=${PW_SQL_ROOT}" >> /root/.my.cnf
chmod 600 /root/.my.cnf

stopwords.txt

Damit der Goobi viewer die Solr Stopwörter auslesen kann muss die entsprechende Sprachdatei abgelegt werden, hier exemplarisch die Deutsche:

 cp /opt/digiverso/viewer/dev/goobi-viewer-docker/solr/goobiviewer/conf/lang/stopwords.txt /opt/digiverso/viewer/config/stopwords.txt

Variablen und Aliase

Folgende Aliase in die /root/.bash_aliases hinzufügen:

cat << "EOF" >>/root/.bash_aliases
alias cata='docker-compose -f /opt/digiverso/viewer/config/docker/docker-compose.yml logs -f --tail="500" viewer'
alias ind='docker-compose -f /opt/digiverso/viewer/config/docker/docker-compose.yml logs -f --tail="500" indexer'
EOF

Übernahme der Änderungen in der aktuellen Session:

. /root/.bashrc

Installation

Für die Installation muss das Goobi viewer Docker git Repository geklont werden:

cd /opt/digiverso/viewer/dev/
git clone https://github.com/intranda/goobi-viewer-docker

Wenn ein eigenes Theme vorliegt muss sichergestellt sein, dass dieses auch geladen werden darf. Liegt es zum Beispiel in einem eigenen Nexus Server bei dem der Zugriff auf den Container passwortgeschützt ist, dann müssen die Zugangsdaten erst lokal hinterlegt werden, zum Beispiel:

docker login -u INTRANDACUSTOMER nexus.intranda.com:4443

Das Setup kennt zwei mögliche Environments. Voreingestellt ist das zum Testen. Für eine Installation im Produktivbetrieb müssen Dateien kopiert und eventuell angepasst werden.

Zuerst die .env-production in das lokale Docker Konfigurationsverzeichnis kopieren, umbenennen und darin Werte anpassen:

cp /opt/digiverso/viewer/dev/goobi-viewer-docker/.env-production /opt/digiverso/viewer/config/docker/.env
sed -i "s|VIEWER_DOMAIN=VIEWER.EXAMPLE.ORG|VIEWER_DOMAIN=${VIEWER_HOSTNAME}|g" /opt/digiverso/viewer/config/docker/.env
sed -i "s|DB_ROOT_PASSWORD=viewer|DB_ROOT_PASSWORD=${PW_SQL_ROOT}|g" /opt/digiverso/viewer/config/docker/.env
sed -i "s|DB_VIEWER_PASSWORD=viewer|DB_VIEWER_PASSWORD=${PW_SQL_VIEWER}|g" /opt/digiverso/viewer/config/docker/.env
sed -i "s|VIEWER_IMAGE=intranda/goobi-viewer-theme-reference:develop|VIEWER_IMAGE=${VIEWER_IMAGE}|g" /opt/digiverso/viewer/config/docker/.env

Anschließend die docker-compose.yml und den solr Ordner kopieren sowie die docker-compose.production.yml kopieren und umbennenen:

cp /opt/digiverso/viewer/dev/goobi-viewer-docker/docker-compose.yml /opt/digiverso/viewer/config/docker/docker-compose.yml
cp -a /opt/digiverso/viewer/dev/goobi-viewer-docker/solr /opt/digiverso/viewer/config/docker/
cp /opt/digiverso/viewer/dev/goobi-viewer-docker/docker-compose.production.yml /opt/digiverso/viewer/config/docker/docker-compose.override.yml

Jetzt können die Container mit den folgenden Befehlen erstmalig gestartet werden:

cd /opt/digiverso/viewer/config/docker/
docker-compose up -d viewer-db solr
docker-compose exec solr solr zk upconfig -n goobiviewer -d /opt/goobiviewer
docker-compose exec solr solr create -c collection1 -n goobiviewer
docker-compose up -d

Benutzeraccount anlegen

Der Goobi viewer verfügt über ein Backend. Mit dem folgenden Kommando wird ein Testaccount mit dem Benutzernamen [e-mail] und dem anfangs festgelegten Passwort in die Datenbank eingefügt:

VIEWER_USERPASS_HASH=$(python3 -c "from passlib.hash import bcrypt; print(bcrypt.using(rounds=10, ident='2a').hash('${VIEWER_USERPASS}'))")
mysql -u viewer -p -D viewer -h 127.0.0.1 -e "INSERT INTO viewer_users (active,email,password_hash,score,superuser) VALUES (1,'${VIEWER_USERNAME}','${VIEWER_USERPASS_HASH}',0,1);"

Updates

Zum Einspielen von Updates muss zuerst das goobi-viewer-docker Repository gepullt werden:

cd /opt/digiverso/viewer/dev/goobi-viewer-docker
git pull

Danach müssen die Unterschiede der folgenden drei Dateien verglichen und entsprechend übernommen beziehungsweise angepasst werden:

diff -u ../../config/docker/.env .env-production  | colordiff
diff -u ../../config/docker/docker-compose.override.yml docker-compose.production.yml  | colordiff
diff -u ../../config/docker/docker-compose.yml docker-compose.yml  | colordiff

Am Ende ist noch zu überprüfen, ob es im Solr Verzeichnis Änderungen gegeben hat.

Diese Punkte sind zusätzlich zu dem bestehenden Core- und Theme Changelog zu verstehen.

Allgemeine Kommandos

An dieser Stelle sind einige Kommandos dokumentiert, um in die Container zu kommen etc.

# Alle Container als Daemon starten,
# wenn -d weggelassen wird wird es im Vordergrund ausgeführt
docker-compose up -d

# Logdateien eines Containers angucken. 
# Mögliche Werte sind solr, zookeeper, viewer, viewer-db, indexer, connector, proxy
docker-compose logs indexer -f

# Einen Docker Container betreten:
docker-compose exec viewer /bin/bash

# Einen Docker Container neu starten
docker-compose restart indexer

# Alles herunterfahren
docker-compose down

# Docker container aktualisieren
docker-compose pull

In einem Container kann zum Beispiel vim mit dem folgenden Kommando nachinstalliert werden:

apt update && apt install vim-nox