iDAI.gazetteer

https://gazetteer.dainst.org/

Gazetteer ist eine Spring Boot-Anwendung. In diesem Repostiory befinden sich sowohl Frontend als auch Backend-Code. Das Frontend wird vom Backend geservt. Es werden lokale Instanzen von MongoDB und Elasticsearch benötigt.

Inhaltsverzeichnis

1. Setup
   • Anforderungen
   • Konfiguration
   • Entwicklungsumgebung
   • Testdaten
   • Indizierung
2. Tests
   • Unit Tests
   • API Tests
3. Struktur
   • i18n
4. Deployment

Setup

Anforderungen

• Ein JDK der Version 21 oder höher (zum Beispiel Oracle OpenJDK)
• Für die Entwicklung, eine Implementierung von Compose (z.B. Docker Compose)

Konfiguration

Gazetteer enthält Defaults für Konfigurationswerte in der src/main/resources/application.properties. Bei Bedarf können diese als Umgebungsvariablen überschrieben werden.

Die Benennung der Umgebungsvariblen sind durch das Konfigurationsframework von Spring aus den Property-Namen generiert, siehe Relaxed Binding.

Für den Prodokutionsbetrieb müssen in der Regel diese Variablen gesetzt werden:

• SMTPHOST
• SMTPPORT
• SENDERMAIL
• MAILUSERNAME
• MAILPASSWORD
• NOTIFICATIONMAIL
• CLUSTER_NAME
• BASEURI
• GEONAMESSOLRURI
• TEMPDIRECTORYPATH
• MONGOREPLICASET

In der Docker-Entwicklungsumgebung müssen keine Umgebungsvariablen gesetzt werden.

Entwicklungsumgebung

Es existiert eine compose.yml um eine Entwicklungsumgebung zu starten.

docker compose up --build startet:

• mongodb: Eine MongoDB mit Testdaten
• elasticsearch: ElasticSearch
• gazetteer: iDAI.gazetteer
• elasticsearch-init: Pusht die ElasticSearch Index Template, erstellt den Index und veranlasst eine Reindizierung.

Testdaten

Beim ersten Start des mongodb-Containers werden diese Testdaten importiert:

• Algerien
• Constantine
• Hippo Regius

Siehe docker/mongo/setup.sh, falls die Daten manuell importiert werden müssen.

Indizierung

Eine Elasticsearch-Reindizierung kann bei laufendem Gazetteer über die Admin-API angestoßen werden:

curl -XPOST admin:password@localhost:8080/admin/reindex

(Zum Inhaltsverzeichnis)

Tests

Unit Tests

./mvnw test

API Tests

API Tests können erweitert werden, indem mit Bruno gazetteer_api_test als Workspace geöffnet wird.

Um die Tests nur auszuführen, kann die Bruno CLI installiert werden.

docker compose up
cd gazetteer_api_test
bru run

(Zum Inhaltsverzeichnis)

Struktur

Backend (Spring Boot) und Frontend (Javascript/AngularJS) werden im gleichen Projekt verwaltet. Der Quellcode des Backends liegt unter src/main/java, der des Frontends unter src/main/webapp/resources/js. Die AngularJS Views werden durch JSPs generiert und liegen unter src/main/webapp/WEB-INF/views/html/partials. Zusätzlich liegen unter src/main/scripts einige in Ruby geschriebene Skripte für den Im- und Export für spezifische Projekte.

i18n

UI-Texte werden in zwei Dateisets eingepflegt.

• src/main/resources/messages_<sprache>.properties
• src/main/webapps/resources/js/i18n/messages*<sprache>.js

(Zum Inhaltsverzeichnis)

Deployment

The gazetteer uses Maven Wrapper to build the docker images.

To build a new image run locally:

./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=ghcr.io/dainst/gazetteer:latest

Alternatively, you may want to tag a new release version:

./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=ghcr.io/dainst/gazetteer:<MAJOR>.<MINOR>.<PATCH>

Finally you have to push the new or updated image to the registry:

docker push ghcr.io/dainst/gazetteer:<version>

In order to push images, you have to authenticate your local machine with the registry, see: Github Container Registry.

(Zum Inhaltsverzeichnis)