gretljobs

Enthält sämtliche Konfigurationsdateien (build.gradle, *.sql) der GRETL-Jobs und eine GRETL-Job-Entwicklungsumgebung. Umfasst zudem das Job DSL Script gretl_job_generator.groovy für den gretl-job-generator Job in Jenkins, der in regelmässigen Abständen das gretljobs-Repository durchsucht und daraus entsprechende Jenkins-Pipelines generiert und ihnen das Jenkinsfile zuweist.

Funktionsweise in Jenkins

In Jenkins besteht zu Beginn nur ein Job gretl-job-generator; das Skript, das er ausführt, ist gretl_job_generator.groovy. Er checkt in regelmässigen Abständen das gretljobs-Repository aus und sucht in allen Ordnern (konfigurierbar) nach Skripten mit Name build.gradle (konfigurierbar).

Wenn er ein solches findet, legt er einen Job an und definiert das Skript in der Datei Jenkinsfile als Code, den der Job ausführen soll. Falls der gretl-job-generator im Ordner des gerade anzulegenden Jobs neben build.gradle auch eine eigene Datei mit Namen Jenkinsfile findet, definiert er als Code für den Job statt des zentralen Jenkinsfiles den Inhalt dieses jobspezifischen Jenkinsfiles (Übersteuerbarkeit). Zudem weist der gretl-job-generator optional dem Job folgende Eigenschaften zu:

• Wer den Job starten darf
• Wieviele Ausführungen eines Jobs aufbewahrt werden sollen
• Ob bei Start des Jobs eine Datei hochgeladen werden muss
• Ob der Job nach Ausführung eines anderen Jobs gestartet werden soll
• Ob der Job in regelmässigen Zeitintervallen gestartet werden soll

Wenn ein GRETL-Job gestartet wird, ermittelt das zugewiesene Skript alle benötigten Parameter und Benutzernamen für den Zugriff auf DBs und andere externe Ressourcen und führt mit Gradle das Skript build.gradle, das im entsprechenden Job-Verzeichnis liegt, aus.

Job starten, der in einem Branch vorliegt

Wenn man einen bereits bestehenden Job bearbeiten möchte, erstellt man hierfür lokal einen separaten Branch und pusht diesen Branch auf GitHub, wenn die Änderungen umgesetzt sind. Im GRETL-Jenkins der Testumgebung und der Integrationsumgebung kann man direkt nach dem Start des Jobs den Namen dieses Branches angeben und so prüfen, ob die Änderungen wie gewünscht funktionieren. Allenfalls noch erforderliche Anpassungen kann man im gleichen Branch vornehmen und sie wieder pushen, usw.

Bei einem neuen Job, der also noch nicht im main-Branch, sondern erst in einem anderen Branch vorliegt, ist das Vorgehen ähnlich; man muss aber zuerst gemäss folgender Anleitung auch im main-Branch den entsprechenden Job-Ordner und eine leere Datei build.gradle anlegen, damit der Job bereits in GRETL-Jenkins aufgelistet wird:

• Den Job wie gehabt lokal in einem Branch entwickeln und den Branch pushen
• Lokal in den main-Branch wechseln und den aktuellen Stand pullen:

  git checkout main && git pull
  

• Auch in diesem Branch einen Ordner mit demselben Namen wie der neue Job anlegen:

  mkdir my_new_job
  

• In diesem Ordner eine leere Datei build.gradle anlegen:

  touch my_new_job/build.gradle
  

• Die leere Datei stagen und committen:

  git add my_new_job/build.gradle && git commit -m "[my_new_job] Initialisierung Job-Verzeichnis"
  

• Diesen "Job-Initialisierungs-Commit" pushen:

  git push origin main
  

• In GRETL-Jenkins z.B. der Testumgebung den Job gretl-job-generator einmal laufenlassen

Nun wird der Job in GRETL-Jenkins der Testumgebung aufgelistet, und man kann wie gewohnt nach dem Start den Branch auswählen, in welchem man den neuen Job entwickelt hat.

Falls der Job ein vom Default abweichendes Jenkinsfile benötigt, muss dieses - nicht leer, sondern funktionsfähig - ebenfalls im main-Branch vorliegen.

Best Practice für das Erstellen von Jobs

• Für jeden neuen Job oder für jede Änderung an einem Job muss ein neuer Entwicklungsbranch erstellt werden:

git checkout -b branchname

• Änderungen müssen immer per Pull Request in den main-Branch eingepflegt werden

build.gradle

• import-Statements zuoberst einfügen
• Danach das apply plugin-Statement einfügen
• Als DB-User bei AGI-Datenbanken gretl, bei den Entwicklungs-Datenbanken dmluser verwenden.
• Als (temporäres) Verzeichnis für Zwischenresultate, beim Herunterladen von Dateien etc. das Build Directory verwenden und mit der Variablen $buildDir darauf zugreifen. (Standardmässig zeigt diese auf den Ordner build innerhalb des Projektverzeichnis.)
• Für Jobs mit File Upload: Die hochzuladende Datei soll im Unterordner in des Build Directory platziert werden ($buildDir/in).
• Immer mindestens einen DefaultTask setzen mit dem das Skript startet. Dadurch muss kein Task beim Aufruf von GRETL mitgegeben werden (Bsp defaultTasks 'transferAgiHoheitsgrenzen').
• println einsetzen wo sinnvoll, also informativ.
• description für Projekt und Tasks machen (Beispiel av_mopublic/build.gradle).
• In den SELECT-Statements kein SELECT * verwenden, sondern die Spalten explizit aufführen.
• Pfade nicht im Unix Style, sondern im mittels Java-Methoden Betriebssystem unabhängig angeben: Paths.get("var","www","maps") oder Paths.get("var/www/maps").
• Pro Tabelle sollte eine SQL-Datei verwendet werden.
• Bitte an den AGI SQL-Richtlinien orientieren.
• t_id in aller Regel nicht von einem Schema in das andere übertragen (Typicherweise Edit-DB -> Pub-DB), damit diese sauber über die Sequenz im Zielschema vergeben wird.
• Variablen mit def definieren und nicht mit ext{}

Migration von V2 auf V3

• Tasks müssen mittels task.register definiert sein.
  • Beispiel für Typ Db2Db:

  tasks.register('HierStehtDerTaskname', Db2Db) {
    dependsOn 'getToken' 
    sourceDb = [db_uri, db_user, db_pass]
    targetDb = ['jdbc:sqlite:gretldemo.sqlite',null,null]
    transferSets = [new TransferSet('some.sql', 'albums_dest', true)];
  }
  

• Datei- und Ordnerreferenzen mittels file() oder files() definieren. Beispiele:
  • outputFile = file("./data.json")
  • localDir = file("downloads")
  • dataFiles = files("attributes.gpkg", "tables.gpkg")
• nodeLabel=gretl-3.2 muss gesetzt werden (in gretljobs.properties)

Zugriff auf Ressourcen

Für den Zugriff auf Datenbanken und andere Ressourcen sollen die Variablen gemäss der folgenden Auflistung verwendet werden. (Die Variablenwerte, die in dieser Auflistung angegeben sind, dienen für die Entwicklung von GRETL-Jobs auf der lokalen Maschine mit Docker Compose.)

# DBs
dbUriEdit=jdbc:postgresql://edit-db/edit
dbUserEdit=dmluser
dbPwdEdit=dmluser
dbUriPub=jdbc:postgresql://pub-db/pub
dbUserPub=dmluser
dbPwdPub=dmluser
dbUriOerebV2=jdbc:postgresql://oereb_v2-db/oereb_v2
dbUserOerebV2=dmluser
dbPwdOerebV2=dmluser
dbUriSimi=
dbUserSimi=
dbPwdSimi=
dbUriIsboden=
dbUserIsboden=
dbPwdIsboden=
dbUriKaso=
dbUserKaso=
dbPwdKaso=
dbUriCapitastra=
dbUserCapitastra=
dbPwdCapitastra=
dbUriEws=
dbUserEws=
dbPwdEws=
dbUriImdaspro=
dbUserImdaspro=
dbPwdImdaspro=

# FTP- und SFTP-Server
ftpUserEmapis=
ftpPwdEmapis=
ftpServerFledermaus=
ftpUserFledermaus=
ftpPwdFledermaus=
ftpServerInfogrips=
ftpUserInfogrips=
ftpPwdInfogrips=
sftpServerWaldportal=
sftpUserWaldportal=
sftpPwdWaldportal=
sftpServerGelan=
sftpUserGelan=
sftpPwdGelan=
sftpServerSEinApp=
sftpUserSEinApp=
# sftpPwdSEinApp gibt es nicht, dafür einen SSH-Key unter /home/gradle/.ssh/id_rsa; siehe Hinweis unterhalb dieser Auflistung
sftpServerSogis=
sftpUrlSogis=build
sftpUserSogis=
sftpPwdSogis=
sftpUserSogisGemdat=
# sftpPwdSogisGemdat gibt es nicht, dafür einen SSH-Key unter /home/gradle/.ssh/id_rsa; siehe Hinweis unterhalb dieser Auflistung
sftpServerZivilschutz=
sftpUserZivilschutz=
sftpPwdZivilschutz=

# Andere Ressourcen
afuAbbaustellenAppXtfUrl=
aiServer=
aiUser=
aiPwd=
awsAccessKeyAda=
awsSecretAccessKeyAda=
awsAccessKeyAfu=
awsSecretAccessKeyAfu=
awsAccessKeyAgi=
awsSecretAccessKeyAgi=
digiplanUrl=
digiplanUser=
digiplanPwd=
igelToken=
infofaunaWfsUser=
infofaunaWfsPwd=
neophytenClientId=
neophytenClientSecret=
simiMetadataServiceUrl=
simiMetadataServiceUser=
simiMetadataServicePwd=
simiTokenServiceUrl=
simiTokenServiceUser=
simiTokenServicePwd=

# Diverse Variablen
dbSearchSchemaPub=
# Der Wert von geoservicesHostName ist je nach Umgebung "geo-t.so.ch", "geo-i.so.ch" oder "geo.so.ch":
geoservicesHostName=geo-t.so.ch
# Der Wert von gretlEnvironment ist je nach Umgebung "test", "integration" oder "production":
gretlEnvironment=
ilivalidatorModeldir=%ITF_DIR;https://geo.so.ch/models/;%JAR_DIR/ilimodels

# Folgende Variablen dürfen in GRETL-Jobs nicht verwendet werden.
# Sie werden aber lokal benötigt, damit dort auch die Schema-Jobs funktionieren.
dbUserEditDdl=ddluser
dbPwdEditDdl=ddluser
dbUserPubDdl=ddluser
dbPwdPubDdl=ddluser
dbUserOerebV2Ddl=ddluser
dbPwdOerebV2Ddl=ddluser

Hinweise:

• Für den Datentransfer SEinApp muss man verwenden: host = sftpServerSEinApp, user = sftpUserSEinApp, identity = file('/home/gradle/.ssh/id_rsa'); der SSH-Key kann im Docker Container verfügbar gemacht werden, indem man den Befehl docker compose run (s. weiter unten) mit der Option -v /local/path/to/id_rsa:/home/gradle/.ssh/id_rsa ergänzt
• Für den Datentransfer Gemdat muss man verwenden: host = sftpServerSogis, user = sftpUserSogisGemdat, identity = file('/home/gradle/.ssh/id_rsa'); der SSH-Key kann im Docker Container verfügbar gemacht werden, indem man den Befehl docker compose run (s. weiter unten) mit der Option -v /local/path/to/id_rsa:/home/gradle/.ssh/id_rsa ergänzt
• Die Anleitung, wie man solche Ressourcen (z.B. DB-Verbindungen) in Jenkins definiert oder bestehende Ressourcen bearbeitet, ist unter https://github.com/sogis/openshift-templates/blob/master/gretl/README.md#create-configmap
• Die Anleitung, wie man neue Credentials anlegt oder bestehende bearbeitet, ist unter https://github.com/sogis/openshift-templates/blob/master/gretl/README.md#create-secret

Verwendung der Variablen ilivalidatorModeldir

Bei IliValidator-Tasks und Ili2gpkgImport-Tasks soll die folgende Option gesetzt werden, damit in den Betriebs-Umgebungen für den Download der benötigten Modelle die Anzahl abzufragender INTERLIS-Repositories reduziert wird:

if (findProperty('ilivalidatorModeldir')) modeldir = ilivalidatorModeldir

(Falls das Modell durch einen vorgängigen Schema-Import (--schemaimport) allerdings bereits in der GeoPackage-Datei enthalten sein sollte, muss die modeldir-Option nicht gesetzt werden, weil ili2gpkgImport dann das Modell im GeoPackage findet und also nicht online danach suchen muss.)

Beispiele: github.com/sogis/gretljobs@eb6f40ffb9/agi_mopublic_pub_export/build.gradle (L62), github.com/sogis/gretljobs@eb6f40ffb9/agi_mopublic_pub_export/build.gradle (L79)

Einrichtung Volltextsuche

Details zur Definition des Suchindexes in Gradle finden sich in der internen Dokumentation Simi - Konfiguration Suche Trigramm

Files

Jeder GRETL-Job braucht im Minimum das File build.gradle. Bei Bedarf platziert man zudem ein File job.properties im Job-Ordner, um den Job in Jenkins zu konfigurieren. Ebenfalls optional kann eine Datei gradle.properties im Job-Ordner platziert werden, um Properties für den Gradle-Prozess zu setzen. Falls der Job in Jenkins mit einem anderen Jenkinsfile als dem Standard-Jenkinsfile gestartet werden soll, muss sein spezifisches Jenkinsfile ebenfalls im Job-Ordner abgelegt werden.

job.properties

Die Datei job.properties kann folgende Eigenschaften des GRETL-Jobs enthalten:

logRotator.numToKeep=30
triggers.cron=H H(1-3) * * *
parameters.stashedFile=myfilename.xyz
parameters.stringParams=PARAMETER_NAME;DEFAULT_VALUE;PARAMETER_DESCRIPTION
triggers.upstream=other_job_name
authorization.permissions=GA_Gretl_barpa

Mit logRotator.numToKeep kann eingestellt werden, wieviele Ausführungen des Jobs aufbewahrt werden sollen, d.h. für wieviele Ausführungen beispielsweise das Logfile vorgehalten wird. Standardwert ist 15. Wenn man diese Einstellung weglässt, werden also die 15 letzten Ausführungen aufbewahrt. Falls man alle Ausführungen aufbewahren möchte, kann man hier den Wert unlimited setzen.

Mit triggers.cron kann eingestellt werden, zu welchem Zeitpunkt der Job automatisch gestartet werden soll. Im Beispiel H H(1-3) * * * wird der Job jeden Tag irgendwann zwischen 01:00 Uhr und 03:59 Uhr ausgeführt. (Dokumentation der Schreibweise siehe https://github.com/jenkinsci/jenkins/blob/master/core/src/main/resources/hudson/triggers/TimerTrigger/help-spec.jelly). Wenn man diese Einstellung weglässt, wird der Job nie automatisch gestartet, und er muss manuell gestartet werden.

Mit parameters.stashedFile kann konfiguriert werden, dass beim manuellen Starten des Jobs eine Datei hochgeladen werden kann. Damit dies funktioniert, ist allerdings ein spezielles Jenkinsfile nötig; siehe unter GRETL-Jobs mit File Upload oder GRETL-Jobs mit File Upload, wobei der ursprüngliche Dateiname beibehalten werden soll. Hinweis: Jobs mit File Upload können nicht aus der Blue Ocean-Oberfläche heraus gestartet werden, sondern nur aus der klassischen Jenkins-Oberfläche heraus.

Mit parameters.stringParams können Parameter definiert werden, für welche man beim manuellen Start des Jobs Werte übergeben kann. Damit man in GRETL auf den Parameterwert zugreifen kann, ist allerdings ein spezielles Jenkinsfile nötig; siehe unter Beim Start des GRETL-Jobs einen Parameter (String) übergeben. Im Jenkinsfile kann mit dem gesetzten Parameternamen auf den Wert des Parameters zugegriffen werden (z.B. mit ${params.MY_PARAMETER_NAME}). Eine Parameter-Definition umfasst jeweils den Parameternamen, optional den Vorgabewert und optional eine Beschreibung. Die drei Werte müssen mit Strichpunkt voneinander getrennt werden. Innerhalb der Werte dürfen deshalb keine Strichpunkte vorkommen (und auch nicht das Zeichen @). Für den Standardwert und die Beschreibung sind Leerschläge zugelassen, und diese können auch aus einem leeren String bestehen. Es ist auch möglich, mehrere String-Parameter zu definieren. Sie müssen mit dem Zeichen @ voneinander getrennt werden. Für die bessere Lesbarkeit ist es ratsam, jeden String-Parameter auf einer eigenen Zeile zu definieren. Hierzu wird ein Backslash am Ende der vorangehenden Zeile benötigt. Beispiel:

parameters.stringParams=bfsnr;0000;BFS-Nr. der Gemeinde welche publiziert werden soll.@\
                        buildDescription;Keine Beschreibung angegeben;Beschreibung/Grund für die Publikation der Daten

Mit triggers.upstream kann eingestellt werden, dass der Job immer dann ausgeführt werden soll, wenn ein bestimmter anderer Job erfolgreich ausgeführt worden ist. Es können hier auch mehrere Jobs angegeben werden, jeweils durch Komma und Leerschlag voneinander getrennt (z.B. other_job_name_1, other_job_name_2).

Mit authorization.permissions kann angegeben werden, welcher Benutzer oder welche Benutzergruppe den Job manuell starten darf. Mehrere Benutzer oder Gruppen können mit Komma getrennt aneinandergereiht werden. Folgende GRETL-spezifischen Benutzergruppen stehen im Moment zur Verfügung:

• GA_Gretl_barpa (ARP)
• GA_Gretl_bdafu (AfU)
• GA_Gretl_bdhba (HBA)
• GA_Gretl_bvtaa (AVT)
• GA_Gretl_edden (ADA)
• GA_Gretl_skkan (Staatskanzlei)
• GA_Gretl_vkfaa (AWJF)
• GA_Gretl_vlwaa (ALW)

Allerdings können auch diejenigen Benutzer oder Gruppen, welche durch globale Berechtigungseinstellungen in Jenkins dazu bereichtigt sind, den Job starten. Wenn man diese Einstellung weglässt, ist es von den globalen Berechtigungseinstellungen abhängig, wer den Job manuell starten darf.

Zudem kann mit der Eigenschaft nodeLabel bestimmt werden, auf welchem Node der Job ausgeführt werden soll. Möglich ist hier der Wert gretl-3.2, damit der Job auf einem Jenkins Agent mit GRETL Version 3.2 ausgeführt wird. Diese Property dient primär dazu, dass bei einem grösseren Versionssprung von GRETL nicht alle Jobs gleichzeitig umgestellt werden müssen. Lässt man diese Property weg, wird der Job auf dem normalen Jenkins Agent (mit dem Label gretl) ausgeführt.

gradle.properties

Die Datei gradle.properties kann z.B. dazu benutzt werden, dem Job mehr Heap Space (gewissermassen mehr RAM) zur Verfügung zu stellen. Um ihm z.B. bis zu 2GB zuzuweisen, muss gradle.properties die folgende Zeile enthalten:

org.gradle.jvmargs=-Xmx2048m

Weitere mögliche Optionen sind unter https://docs.gradle.org/current/userguide/build_environment.html dokumentiert.

Jenkinsfile

Das Jenkinsfile sorgt dafür, dass ein GRETL-Job aus Jenkins heraus gestartet werden kann. In der Regel braucht ein GRETL-Job kein eigenes Jenkinsfile, denn es kommt standardmässig das "zentrale" Jenkinsfile zum Einsatz.

In speziellen Fällen benötigen GRETL-Jobs ein eigenes Jenkinsfile; hierzu kopiert man das Jenkinsfile eines bereits bestehenden, ähnlichen Jobs in den GRETL-Job-Ordner. Es soll dabei nicht verändert oder möglichst nur minimal angepasst werden, damit alle Jenkinsfiles soweit möglich identisch sind.

Die speziellen Fälle und die jeweiligen Vorlagen sind in jenkinsfile_docs.md beschrieben.

GRETL Docker Image verwenden

Für die Entwicklung von GRETL-Jobs kann GRETL mit docker compose als Docker-Container genutzt werden.

Voraussetzungen

Damit die GRETL-Jobs auch lokal funktionieren, muss im lokalen Home-Verzeichnis die Datei gretljobs.properties vorhanden sein. Sie enthält die verschiedenen Verbindungsparameter zu den lokalen Entwicklungs-DBs und andere benötigte Variablen. Was in dieser Datei drinstehen muss, ist im Abschnitt Zugriff auf Ressourcen ersichtlich (man kann diese Liste direkt kopieren).

Entwicklungs-DBs nutzen

GRETL-Container und Entwicklungs-DBs starten

docker compose up -d

bzw. wenn man sich im Verzeichnis schema-jobs befindet:

docker compose -f ../gretljobs/compose.yaml up -d

Mit diesem Befehl werden ein GRETL-Container und zwei DB-Container gestartet, von denen einer eine edit-DB, der andere eine pub-DB enthält.

Mit der ersten Variante des Befehls startet man GRETL und die Entwicklungs-DBs, wenn man sich im gretljobs-Verzeichnis befindet. Mit der zweiten Variante startet man sie, wenn man sich im schema-jobs-Verzeichnis befindet.

Auch die weiter unten in diesem Kapitel angegebenen Befehle lassen sich auf diese Art jeweils auch aus dem schema-jobs-Verzeichnis heraus ausführen. Man muss in diesem Fall also dem Befehl die Option -f ../gretljobs/compose.yaml übergeben, um auf die Datei compose.yaml des Verzeichnis gretljobs verweisen.

Voraussetzung, damit dies funktioniert: Die Ordner gretljobs und schema-jobs müssen sich im gleichen übergeordneten Ordner befinden.

GRETL-Jobs, die eine ÖREB-DB benötigen:

docker compose -f compose.yaml -f compose.oereb_v2.yaml up -d

So wird zusätzlich zur edit-DB und zur pub-DB auch eine oereb_v2-DB gestartet für GRETL-Jobs, die eine solche benötigen.

Wichtig: In diesem Fall müssen auch die nachfolgenden Compose-Befehle jeweils mit der Option -f compose.yaml -f compose.oereb_v2.yaml aufgerufen werden, damit sie auch die ÖREB-DB mit einschliessen.

GRETL-Jobs, die eine DB für das Processing von Daten benötigen:

docker compose -f compose.yaml -f compose.processing.yaml up -d

So wird zusätzlich zur edit-DB und zur pub-DB auch eine processing-DB gestartet für GRETL-Jobs, die eine solche benötigen.

Wichtig: In diesem Fall müssen auch die nachfolgenden Compose-Befehle jeweils mit der Option -f compose.yaml -f compose.processing.yaml aufgerufen werden, damit sie auch die Processing-DB mit einschliessen.

GRETL-Container und Entwicklungs-DBs stoppen

docker compose stop

bzw. wenn man sich im Verzeichnis schema-jobs befindet:

docker compose -f ../gretljobs/compose.yaml stop

So werden der GRETL-Container und die Entwicklungs-DB-Container gestoppt. Die Container und alle ihre Dateien bleiben erhalten, sind aber nicht mehr erreichbar, solange sie gestoppt sind. Die Daten der DBs bleiben ebenfalls erhalten.

GRETL-Container und Entwicklungs-DBs stoppen und Docker-Container löschen

docker compose down

bzw. wenn man sich im Verzeichnis schema-jobs befindet:

docker compose -f ../gretljobs/compose.yaml down

Der GRETL-Container und die Entwicklungs-DB-Container werden gestoppt und gelöscht. Auch das von Docker Compose angelegte Docker-Netzwerk wird gelöscht. Die Daten der DBs bleiben auch in diesem Fall erhalten, weil sie in Docker-Volumes gespeichert sind, die hierbei nicht gelöscht werden.

Daten der Entwicklungs-DB-Container löschen

docker volume rm gretljobs_pgdata_edit gretljobs_pgdata_pub

bzw. für die ÖREB-DB oder die Processing-DB

docker volume rm gretljobs_pgdata_oereb_v2
docker volume rm gretljobs_pgdata_processing

Mit diesem Befehl werden die Volumes der Entwicklungs-DB-Container und damit die Daten in den Entwicklungs-DBs gelöscht. (Die DB-Container müssen vorgängig mit dem Befehl docker compose down ebenfalls gelöscht werden.)

Verbindungsparameter für die Entwicklungs-DBs

Die Entwicklungs-DBs sind z.B. aus DBeaver oder psql mit folgenden Verbindungsparametern erreichbar:

Edit-DB:

• Hostname: localhost
• Port: 54321
• DB-Name: edit
• Benutzer mit DDL-Rechten: ddluser (zum Anlegen von Schemen, Tabellen usw.)
• Benutzer mit DML-Rechten: dmluser (für Lese- und Schreibzugriff)
• Passwörter: lauten jeweils gleich wie der Benutzername

Publikations-DB:

• Hostname: localhost
• Port: 54322
• DB-Name: pub
• Benutzer mit DDL-Rechten: ddluser (zum Anlegen von Schemen, Tabellen usw.)
• Benutzer mit DML-Rechten: dmluser (für Lese- und Schreibzugriff)
• Passwörter: lauten jeweils gleich wie der Benutzername

ÖREB-DB:

• Hostname: localhost
• Port: 54323
• DB-Name: oereb_v2
• Benutzer mit DDL-Rechten: ddluser (zum Anlegen von Schemen, Tabellen usw.)
• Benutzer mit DML-Rechten: dmluser (für Lese- und Schreibzugriff)
• Passwörter: lauten jeweils gleich wie der Benutzername

Processing-DB:

• Hostname: localhost
• Port: 54324
• DB-Name: processing
• Benutzer mit Superuser-Rechten: processing
• Passwort: lautet gleich wie der Benutzername

GRETL-Job ausführen

docker compose exec -u $UID gretl-service gretl --rerun-tasks --project-dir=MY_JOB_NAME [OPTION...] [TASK...]

bzw. wenn man sich im Verzeichnis schema-jobs befindet:

docker compose -f ../gretljobs/compose.yaml exec -u $UID gretl-service gretl --rerun-tasks --project-dir=MY_JOB_NAME [OPTION...] [TASK...]

Dieser Befehl startet den GRETL-Job MY_JOB_NAME.

Beispiele:

docker compose exec -u $UID gretl-service gretl --rerun-tasks --project-dir=arp_nutzungsplanung_pub

docker compose exec -u $UID gretl-service gretl --rerun-tasks --project-dir=arp_nutzungsplanung_pub -Pbfsnr=2408 importXTF_stage

Wichtig: Um den Job gründlich zu testen, ist es sinnvoll, von Zeit zu Zeit den Inhalt des Build Directory zu löschen.

Erläuterungen:

• MY_JOB_NAME muss durch den Namen des auszuführenden GRETL-Jobs (den Ordnernamen) ersetzt werden.
• Mit OPTION... (optional) können beliebige Gradle-Optionen übergeben werden, z.B.: --rerun-tasks, --stacktrace, --info, --debug, --console=rich, -Pmyprop=myvalue, -Dmyprop=myvalue. Dokumentation der Gradle-Optionen: https://docs.gradle.org/current/userguide/command_line_interface.html
• Mit der Option --rerun-tasks wird GRETL gezwungen, auch diejenigen Tasks auszuführen, die es als bereits UP-TO-DATE erkannt hat.
• Mit der Option --no-daemon wird der Job ohne Nutzung des Daemons ausgeführt (dies war das bisherige Verhalten des GRETL-Containers).
• Mit TASK... (optional) kann ein oder mehrere Tasks angegeben werden, die von GRETL ausgeführt werden sollen. Falls man nichts angibt, werden die in build.gradle definierten defaultTasks ausgeführt.
• Falls man einen anderen GRETL-Image-Tag verwenden möchte (z.B. latest oder 3.2.861), erstellt man vor dem Ausführen von docker compose up im Verzeichnis gretljobs eine Datei mit Name .env mit dem Inhalt GRETL_IMAGE_TAG=MYTAG, z.B. GRETL_IMAGE_TAG=3.2.861. Zu beachten ist, dass danach alle Jobs mit diesem GRETL-Tag ausgeführt werden, solange dies so in der Datei .env steht und solange der GRETL-Container besteht.
• Falls ein bestimmter Job Zugriff auf Daten in einem Persistent Volume Claim (PVC) benötigt, lässt sich dies lokal abbilden, indem man docker compose run mit einem Volume Mount (Option -v ...) gemäss folgendem Beispiel benutzt:

  docker compose run --rm -u $UID -v /local/path:/work/datahub/DMAV_FixpunkteAVKategorie3_V1_0 gretl-service gretl --rerun-tasks --project-dir=MY_JOB_NAME [OPTION...] [TASK...]
  

  In diesem Fall wird ein separater GRETL-Container gestartet, so dass die Vorteile des Gradle Daemon nicht zum Einsatz kommen. (Mit Vorteil erstellt man das zu mountende lokale Verzeichnis (im Beispiel /local/path) bereits vor dem Ausführen des Befehls; andernfalls wird es zwar von Docker Compose automatisch angelegt, allerdings mit Schreibberechtigung nur für den User root.)

Schema-Job ausführen

docker compose exec -u $UID --workdir //home/gradle/schema-jobs/shared/schema gretl-service \
  gretl --rerun-tasks -PtopicName=MY_TOPIC_NAME -PschemaDirName=MY_SCHEMA_DIRECTORY_NAME [-PdbName=MY_DB_NAME] [OPTION...] TASK...

bzw. wenn man sich im Verzeichnis schema-jobs befindet:

docker compose -f ../gretljobs/compose.yaml exec -u $UID --workdir //home/gradle/schema-jobs/shared/schema gretl-service \
  gretl --rerun-tasks -PtopicName=MY_TOPIC_NAME -PschemaDirName=MY_SCHEMA_DIRECTORY_NAME [-PdbName=MY_DB_NAME] [OPTION...] TASK...

Dieser Befehl startet den Schema-Job im Ordner MY_TOPIC_NAME\MY_SCHEMA_DIRECTORY_NAME.

Voraussetzung: Die Ordner gretljobs und schema-jobs müssen sich im gleichen übergeordneten Ordner befinden.

Beispiel:

docker compose exec -u $UID --workdir //home/gradle/schema-jobs/shared/schema gretl-service \
  gretl --rerun-tasks -PtopicName=agi_mopublic -PschemaDirName=schema_pub createSchema configureSchema

bzw. wenn man sich im Verzeichnis schema-jobs befindet:

docker compose -f ../gretljobs/compose.yaml exec -u $UID --workdir //home/gradle/schema-jobs/shared/schema gretl-service \
  gretl --rerun-tasks -PtopicName=agi_mopublic -PschemaDirName=schema_pub createSchema configureSchema

Erläuterungen:

• MY_TOPIC_NAME muss durch den Namen des Topics (den Ordnernamen) und MY_SCHEMA_DIRECTORY_NAME durch den Namen des Unterordners, in welchem die Schema-Eigenschaften definiert sind, ersetzt werden.
• Die Option -PdbName=MY_DB_NAME (optional) ist nur in Ausnahmefällen nötig, z.B. wenn das Schema in einer anderen DB angelegt werden soll, als in der Datei schema.properties definiert ist.
• Mit OPTION... (optional) können beliebige Gradle-Optionen übergeben werden, z.B.: --console=rich, -Pmyprop=myvalue, -Dmyprop=myvalue.
• Mit TASK... muss angegeben werden, welcher Task bzw. welche Tasks von GRETL ausgeführt werden sollen, z.B. dropSchema oder createSchema configureSchema.
• Der Task configureSchema setzt, wenn er lokal, d.h. in einer Development-Umgebung ausgeführt wird, gleichzeitig auch die Berechtigungen auf den DB-Schemen und Tabellen so, dass GRETL-Jobs auf diese Schemen zugreifen können (Lese- und Schreibrechte). Das heisst, dass lokal der Task grantPrivileges im Normalfall nicht ausgeführt werden muss.

Daten in die Entwicklungs-DBs importieren

Mittels dump restore

Beschreibung des Ablaufs siehe: copy_schema_to_dev.md

Alternativ: Mittels Schema-Job Task importDevelopmentData

Wenn der Schema-Job entsprechend konfiguriert ist, kann man unter bestimmten Bedingungen mit dem Task importDevelopmentData automatisiert Daten in die Entwicklungs-DBs importieren.

Voraussetzungen:

• Die Daten müssen online unter https://files.geo.so.ch als .xtf verfügbar sein
• In der Datei schema.properties im Schema-Job muss die Property data.themePublicationName gesetzt sein (z.B. data.themePublicationName = ch.so.arp.nutzungsplanung.kommunal)
• Falls es sich um ein Schema handelt, das Datasets enthält, muss entweder in schema.properties auch die Property data.dataSets gesetzt sein (z.B. data.dataSets = 2403,2405,2408), oder man muss beim Ausführen des Tasks importDevelopmentData die Property data.dataSets übergeben, z.B. -Pdata.dataSets=2403,2405,2408. Sowohl in schema.properties als auch bei der Übergabe als Property beim Ausführen des Tasks ist auch der Wert defaultDataSets möglich (z.B. -Pdata.dataSets=defaultDataSets); hinter defaultDataSets sind die BFS-Nummern aller Gemeinden des Kantons Solothurn hinterlegt.

Hinweise zu den DB-Containern

Die Rollen (Benutzer und Gruppen) der produktiven DBs importieren

Um auch die in den produktiven DBs vorhandenen DB-Rollen in den Entwicklungs-DBs verfügbar zu haben, kopiert man die Datei mit den DB-Rollen (die "Globals") vom geoutil-Server auf seine lokale Maschine, entfernt mit einem sed-Befehl diejenigen Zeilen, die für die Entwicklungs-DBs nicht nötig sind, und importiert sie dann mit psql in die Entwicklungs-DBs:

scp geoutil.verw.rootso.org:/opt/workspace/dbdump/globals_geodb.rootso.org.dmp /tmp
sed -E -i.bak '/^CREATE ROLE (postgres|admin)\;/d; /^ALTER ROLE (postgres|admin) /d' /tmp/globals_geodb.rootso.org.dmp
psql --single-transaction -h localhost -p 54321 -d edit -U postgres -f /tmp/globals_geodb.rootso.org.dmp
psql --single-transaction -h localhost -p 54322 -d pub -U postgres -f /tmp/globals_geodb.rootso.org.dmp

Für den Fall, dass psql auf der lokalen Maschine nicht installiert ist, kopiert man stattdessen die Globals zuerst in den laufenden Container und führt danach den psql-Befehl innerhalb des Containers aus:

docker cp /tmp/globals_geodb.rootso.org.dmp gretljobs_pub-db_1:/tmp
docker exec -e PGHOST=/tmp -it gretljobs_pub-db_1 psql --single-transaction -d pub -f /tmp/globals_geodb.rootso.org.dmp
docker cp /tmp/globals_geodb.rootso.org.dmp gretljobs_edit-db_1:/tmp
docker exec -e PGHOST=/tmp -it gretljobs_edit-db_1 psql --single-transaction -d edit -f /tmp/globals_geodb.rootso.org.dmp

Troubleshooting

Wenn folgende Fehlermeldung auftritt, muss das .gradle Ordner im Job Ordner gelöscht werden.

Caused by: java.io.FileNotFoundException: /home/gradle/project/.gradle/4.2.1/fileHashes/fileHashes.lock (Permission denied)