Installation

Rocklog Edge nutzt als Laufzeitumgebung docker compose und besteht aus verschiedenen Diensten. Diese Dienste werden ergänzt durch allgemeine Infrastrukturkomponenten auf dem genutzten Host wie nginx als Webserver. Die Nutzung von rocklog Edge macht eine Anpassung der Konfiguration dieser Infrastrukturkomponenten notwendig. Dieses Dokument beschreibt die notwendigen Schritte zum erstmaligen Bau und zum Einsatz von rocklog Edge auf cloud oder on-Premise Infrastrukturen.

Anlage eines übergeordneten Arbeitsverzeichnis

Dieses Arbeitsverzeichnis wird die einzelnen Dienste aufnehmen sowie Konfigurationsdateien und Startskripte bereithalten.

mkdir werner
cd werner

Auschecken der Github Repositories

in das Arbeitsverzeichnis werden die notwendigen Projekte geclont.

• werner-docker DBMS, Postinstallroutinen, Identity Provider keycloak
• werner-backend Businesslogik sowie Schnittstellen und deren Dokumentation
• werner-server Webapp für PC
• werner-pwa Mobiler Client, offlinefähig

nun wird das Script zum Bau, zur Konfiguration und zum Start der Anwendung in das Arbeitsverzeichnis kopiert

cp werner-docker/start.sh
sudo chown +x start.sh

Generieren weiterer Konfigurationsfiles (nginx / keycloak)

Durch den Aufruf des start.sh Scripts im Konfigurationsmodus werden folgende Artefakte erzeugt

• nginx location file <project>.rocklog.ch.conf Dieses File muss nach der Erzeugung nach /etc/nginx/sites-enabled kopiert werden und exponiert über den nginx des hostsystems die benötigten subdomains <project>.rocklog.ch, <project>-pwa.rocklog.ch, <project>-kc.rocklog.ch
• keycloak realm file <project>.realm.json Durch den Import dieses Files in der Keycloak Admin Console wird ein initialer realm <project> sowie dem client <project> unter dessen id werner-server angelegt. Weiterhin umfasst dieses File Konfigurationsparameter für SMTP.

Anlage der Root Konfiguration .env.<project>

Diese Datei muss im Arbeitsverzeichnis angelegt werden und umfasst wichtige Umgebungsvariablen, die für den Aufstart von rocklog Edge benötigt werden.

WERNER_BACKEND_VERSION=0.1.9
WERNER_BACKEND_PORT=9000
WERNER_SERVER_PORT=9001
WERNER_PWA_PORT=9002
WERNER_POSTGRES_PORT=9003
WERNER_REPL_PORT=9004
WERNER_KEYCLOAK_PORT=9005
WERNER_PROFILE=library
DB_BACKUP_DIR=../db_backup_<project>
WERNER_AUTH_REQUIRED=true
KC_URL=https://<project>-kc.rocklog.ch
KC_REALM=<project>
WERNER_KEYCLOAK_ADMIN_USER=<your desired admin username>
WERNER_KEYCLOAK_ADMIN_PASSWORD=<your desired admin password>
CUSTOM_EDN_FILE=../custom-path/custom-config.edn

• WERNER_BACKEND_VERSION Image von werner-backend, welches genutzt wird um den Container für die Komponente werner-backend zu starten.
• WERNER_BACKEND_PORT Port, unter welchem auf dem Host auf die Businesslogik sowie deren Schnittstellen zugegriffen werden können. Dieser Port ist nicht von ausserhalb des Hosts verfügbar.
• WERNER_SERVER_PORT Port, unter welchem auf dem Host auf die PC Webapp zugegriffen werden kann. Dieser Port ist nicht von ausserhalb des Hosts verfügbar.
• WERNER_PWA_PORT Port, unter welchem auf dem Host auf den mobilen Clientzugegriffen werden kann. Dieser Port ist nicht von ausserhalb des Hosts verfügbar.
• WERNER_POSTGRES_PORT Port, unter welchem auf dem Host auf das Postgres DBMS zugegriffen werden kann. Dieser Port ist nicht von ausserhalb des Hosts verfügbar.
• WERNER_REPL_PORT Port, unter welchem auf dem Host auf die Eingabeaufforderung des Lisp Prozesses zugegriffen werden kann. Dieser Port ist nicht von ausserhalb des Hosts verfügbar.
• WERNER_KEYCLOAK_PORT Port, unter welchem auf dem Host auf die Admin Console des Identity Providers Keycloak zugegriffen werden kann. Dieser Port ist nicht von ausserhalb des Hosts verfügbar.
• WERNER_PROFILE library|container
• DB_BACKUP_DIR Wird durch eine cronjob genutzt, um das regelmässig erzeugte vollständige Backup abzulegen. Der Cronjob überträgt das Backup bereits auf einen Sicherungsserver. Das hier konfigurierte Verzeichnis wird als bind mount des Containers werner-docker gebunden und erlaubt den Zugriff auf das Backup vom Host aus.
• WERNER_AUTH_REQUIRED Muss auf true gesetzt werden, damit die Authentifizierung des Users durchgeführt wird
• KC_URL Unter dieser URL ist die Admin Console des Identity Providers Keycloak verfügbar
• KC_REALM Dieser Realm fasst alle User zusammen, welche Zugriff auf die Anwendung haben sowie alle Einstellungen im Bereich Authentifizierung und Authorisierung
• CUSTOM_EDN_FILE (Optional) benennt ein .edn File zur Laufzeitkonfiguration der Systembestandteile des Businesslogikservers werner-backend. Dieses File kann z.B. Schnittstellen- und Jobkonfigurationen umfassen. Der Pfad zur .edn Datei muss entweder absolut oder relativ startend mit "./" gegeben sein

Sämtliche Ports müssen disjunkt von jenen anderer Projekte sein, die auf dem Host bereitgestellt werden.

Elemente der werner-backend Configuration (.edn file)

Nachfolgend ist eine vom Standard abweichende .edn Datei gegeben, die Vorlage für eigene Konfiguration dienen kann.

{:server/jetty {:handler #ig/ref :werner/app :port 8080}
 :werner/router {}
 :werner/app {:jdbc-url #ig/ref :db/postgres :router #ig/ref :werner/router}
 :werner/walkable-parser {:jdbc-url #ig/ref :db/postgres}
 ;; we use the DB config from the env not exposing any secrets here
 :db/postgres {}
 :domain/job {:werner/app #ig/ref :werner/app}
 :domain/device {:werner/app #ig/ref :werner/app}
 :tasks/scheduler {:db/postgres #ig/ref :db/postgres}
 :tasks/image-fetch-prepare-cron {:schedule "2 /15 * * * * *" :tasks/scheduler #ig/ref :tasks/scheduler :limit 2000}
 :tasks/image-fetch-cron {:schedule "4 /4 * * * * *" :tasks/scheduler #ig/ref :tasks/scheduler :limit 50 :max-size-kb 250}
 :tasks/import_stocks_from_filesystem {
  :db/postgres #ig/ref :db/postgres
  :specs [{
    :separator ","
    :quote \"
    :encoding "UTF-8"
    :locale "de_CH" ; Locale for Switzerland (German)
    :job_name "import stocks initially"
    :update-key :hostsystem_reference
    ;; PID,Barcode,Call Number,Title,Author,Publication Date
    :columns [["PID" :hostsystem_reference :string]
              ["Barcode" :barcode :string]
              ["Call Number" :call_no :string]
              ["Title" :title :string]
              ["Author" :author :string]
              ["Publication Date" :year_of_publication :string]]
    :invariants {:article/ident "Buch"}
    :path-to-watch "/tmp/werner/interface/stock-import/in"
    :path-to-copy-to "/tmp/werner/interface/stock-import"
    :files-to-watch-regex "*\\.csv"}]}


 ;;:interface/cds-job-import {:werner/app #ig/ref :werner/app 
 ;;                                :domain/job #ig/ref :domain/job
 ;;                                :path-to-watch "/tmp/cds" 
 ;;                                :path-to-export "/tmp/cds/export"
 ;;                                :ident "CDS Auftragsimport" :default_order_type/ident "Containerbereitstellung" :order_type_with_recycling/ident "Containerbereitstellung mit Entsorgung"}
}

Anforderungen an Credentials des Keycloak Admin Users

Die Einstellungen WERNER_KEYCLOAK_ADMIN_USER und WERNER_KEYCLOAK_ADMIN_PASSWORD sind für das erste Login auf der Adminconsole von Keycloak massgebend. Die Credentials des Admin Users sollten nachträgtlich geändert pro Projekt, im Passwortsafe abgelegt und die 2FA aktiviert werden.

Erzeugen der abgeleiteten Konfigurationsdateien

Die Dateien <project>.rocklog.ch.conf sowie <project>.realm.json werden durch den Aufruf des folgenden Kommandos im Arbeitsverzeichnis erzeugt.

❯ ./start.sh <project> .env.<project> config
Generating Nginx configuration...
Generated Nginx configuration at <project>.rocklog.ch.conf. Copy this to /etc/nginx/sites-enabled/
Generated Keycloak realm configuration at <project>.realm.json

Bau des Projektes

Durch die Eingabe des folgenden Kommandos im Arbeitsverzeichnis werden alle Container und notwendigen Volumen erzeugt.

./start.sh <project> .env.<project> build

Sind alle Komponenten erzeugt und die Container erfolgreich gestartet, können die Container mit CTRL+C beendet werden

Start des Projektes

Durch die Eingabe des folgenden Kommandos im Arbeitsverzeichnis werden alle Container im Hintergrund (Daemon) gestartet.

./start.sh <project> .env.<project> run

Beenden des Projektes

Durch die Eingabe des folgenden Kommandos im Arbeitsverzeichnis werden alle zum Projekt gehörenden Container gestoppt.

docker compose -p <project> down