Store (neu)

Information

Dies ist die Dokumentation des neuen Stores, der in v3.5 eingeführt wurde. Für den alten Store, der in v4.0 entfernt werden wird, siehe Store.

Der Store repräsentiert alle Dateien, die ein Deployment von ldproxy ausmachen, außer der Anwendung selbst. Dazu gehören alle Konfigurationsdateien, aber auch andere Ressourcen wie File-Datenbanken oder Caches. Im einfachsten Fall existieren alle diese Dateien im lokalen Daten-Verzeichnis, aber das wäre zum Beispiel für Cloud-Umgebungen kein skalierbarer Ansatz.

Die Flexibilität, um solchen unterschiedlichen Anforderungen gerecht zu werden, bieten Store Sources, die theoretisch die Integration aller erdenklichen lokalen oder entfernten Datei-Quellen ermöglichen. Der Store kann aus einer beliebigen Anzahl von Store Sources zusammengesetzt werden. Wie das funktioniert, wird in den folgenden Abschnitten beschrieben.

Optionen

Dies sind die Konfigurationsoptionen für den Key store in der globalen Konfiguration.

Name	Default	Beschreibung	Typ	Seit
`mode`	`RW`	`RW` oder `RO`. Kann auf `RO` gesetzt werden, falls jeglicher Schreibvorgang verboten werden soll. Ansonsten siehe `mode` für Store sources.	string	v2.0
`sources`	`[{type:FS,src:.}]`	Liste von Store sources. Der Default ist das Data-Verzeichnis. Die Liste ist erweiterbar, d.h. Einträge aus Konfigurationsdateien werden zum Default hinzugefügt.	array	v3.5

Store Sources

Optionen

Dies sind allgemeine Optionen, die für alle Source Types gelten. Spezifische Optionen können in Source Types beschrieben sein.

Name	Default	Beschreibung	Typ	Seit
`type`		Der Source Type.	string	v3.5
`content`	`ALL`	Der Content Type.	string	v3.5
`mode`	`RO`	Kann auf `RW` gesetzt werden, um die Source schreibbar zu machen.	string	v3.5
`src`		Der Source-Pfad, siehe Source Types für Details.	string	v3.5
`prefix`	`null`	Prefix für Datei-Pfade einer Source, kann benötigt werden, um Verzeichnisstrukturen anzugleichen.	string	v3.5
`include`	`[]`	Glob-Ausdrücke für Datei-Pfade einer Source die inkludiert werden sollen, alle anderen werden ignoriert. Kann benötigt werden, um Verzeichnisstrukturen anzugleichen.	array	v3.6
`exclude`	`[]`	Glob-Ausdrücke für Datei-Pfade einer Source, die ignoriert werden sollen. Kann benötigt werden, um Verzeichnisstrukturen anzugleichen.	array	v3.6
`archiveRoot`	`/`	Kann gesetzt werden, um ein Unterverzeichnis aus einer ZIP-Datei zu verwenden.	string	v3.5
`parts`	`[]`	Liste von partiellen Sources für Content Type MULTI.	array	v3.5

Source Types

Store Sources können verschiedene Source Types haben, was die Integration beliebiger lokaler oder entfernter Dateien erlaubt.

`FS`

Zugriff auf Dateien aus dem lokalen Dateisystem. src muss ein Pfad zu einem Verzeichnis oder einer ZIP-Datei sein. Der Pfad kann entweder absolut oder relativ zum Datenverzeichnis sein. FS Verzeichnisse sind standardmäßig beschreibbar.

`S3`

Zugriff auf Dateien aus einem S3-kompatiblen Object-Store. src muss ein relativer Pfad sein, der aus einem Host und einem Bucket besteht, z.B. my-minio/demo oder s3.eu-central-1.amazonaws.com/demo.

Außerdem müssen ein accessKey und ein secretKey für die Store Source angegeben werden.

`HTTP`

Zugriff auf Dateien von einem Webserver. src muss eine gültige URL sein, die auf eine ZIP-Datei verweist. Kann nicht beschreibbar sein.

`GITHUB`

Zugriff auf Dateien aus einem GitHub-Repository. Convenience-Wrapper für HTTP. src muss ein relativer Pfad sein, der sich aus der Organisation, dem Repository und einem optionalen Branch (Standard ist main) zusammensetzt, z.B. ldproxy/demo:main.

`GITLAB`

Zugriff auf Dateien aus einem GitLab-Repository. Convenience-Wrapper für HTTP. src muss ein relativer Pfad sein, der aus einem optionalen Host (Standard ist gitlab.com), der Organisation, dem Repository und einem optionalen Branch (Standard ist main) besteht, z.B. my-gitlab/ldproxy/demo:main.

`GITEA`

Zugriff auf Dateien aus einem Gitea-Repository. Convenience-Wrapper für HTTP. src muss ein relativer Pfad sein, der aus einem Host, der Organisation, dem Repository und einem optionalen Branch (Standard ist main) besteht, z.B. my-gitea/ldproxy/demo:main.

Content Types

Store Sources können verschiedene Content Types haben, was eine feingranulare Zusammensetzung des Stores erlaubt. Der ALL Typ wäre ausreichend, da er alle anderen Typen enthält, aber dann müssten alle Sources der geforderten Verzeichnisstruktur folgen. Die anderen Typen erlauben es, Dateien aus einer beliebigen Verzeichnisstruktur einzubinden, was vielleicht praktisch oder sogar notwendig sein kann, wenn die Dateien auch in einem anderen Kontext verwendet werden.

`ALL`

Store Sources mit dem Content Type ALL sind ein Container für diese anderen Content Types:

CFG im Pfad cfg.yml
ENTITIES im Pfad entities/
VALUES im Pfad values/
RESOURCES im Pfad resources/

`CFG`

Store Sources mit dem Content Type CFG enthalten eine einzelne YAML-Datei mit globalen Konfigurations-Einstellungen.

`ENTITIES`

Entities bilden den primären benutzerdefinierten Teil der Anwendung, zum Beispiel APIs und Daten-Provider. Die Konfiguration der Entities erfolgt in YAML-Dateien.

Store Sources mit dem Content Type ENTITIES sind ein Container für diese anderen Content Types:

INSTANCES im Pfad instances/
DEFAULTS im Pfad defaults/
OVERRIDES im Pfad overrides/

`INSTANCES`*

Store Sources mit dem Content Typ INSTANCES enthalten die Haupt-Definitionen von Entities. Die Pfade setzen sich aus einem Entity-Typ und einer Entity-Id zusammen, zum Beispiel services/foo.yml. Eine Instanz muss einzigartig sein, sie kann also über alle Store Sources hinweg nur einmal definiert sein.

`DEFAULTS`

Store Sources mit dem Content Type DEFAULTS können Default-Konfigurationen für die verschiedenen Entity-Typen enthalten, die vor der Instanz-Konfiguration angewendet werden. Die Pfade bestehen aus einem Entity-Typ und einem optionalen Entity-Sub-Typ, zum Beispiel würde services.yml allgemeine Defaults für alle Sub-Typen enthalten und services/ogc_api.yml würde Defaults für den Sub-Typ ogc_api. Einige Entity-Typen können auch eine weitere Ebene von Dateien mit partiellen Defaults erlauben, zum Beispiel services/ogc_api/metadata.yml.

`OVERRIDES`

Store Source mit dem Content Type OVERRIDES können Override-Konfigurationen für Entities enthalten, die nach der Instanz-Konfiguration angewendet werden. Die Pfade müssen mit den Instanz-Pfaden übereinstimmen, zum Beispiel services/foo.yml.

`VALUES`

Store Sources mit dem Content Type VALUES können sekundäre benutzerdefinierte Konfigurationen enthalten, z.B. Code-Listen. Die Konfiguration der Values erfolgt in YAML- oder JSON-Dateien. Die Pfade setzen sich aus einem Value-Typ und einem beliebigen Datei-Pfad zusammen, zum Beispiel codelists/foo/bar.yml. Die Pfad-Muster werden von den Komponenten definiert, die sie benötigen, ihre Dokumentation wird etwas enthalten wie "sind Values mit dem Typ codelists und Pfad foo/bar". Einige Funktionen benötigen möglicherweise auch eine beschreibbare Store Source, um richtig zu funktionieren.

`RESOURCES`

Store Sources mit dem Content Type RESOURCES können alle anderen Dateien enthalten, die von der Anwendung benötigt werden. Die Pfade werden von den Komponenten definiert, die sie benötigen, ihre Dokumentation wird etwas enthalten wie "sind Ressourcen mit dem Pfad foo/bar". Einige Funktionen benötigen möglicherweise auch eine beschreibbare Store Source, um richtig zu funktionieren.

`MULTI`

Store Sources mit dem Content Type MULTI sind ein Container mit einer gemeinsamen Wurzel, die eine Liste von anderen Content Types enthält. Dieser Typ kann der Einfachheit halber verwendet werden, zum Beispiel für eine ALL-ähnliche Store Source mit einer anderen Verzeichnisstruktur.

Reihenfolge

`CFG`

Globale Konfigurationsdateien werden beim Start in der Reihenfolge der Store Sources gelesen und zusammengeführt.

Theoretisch könnte jede globale Konfigurationsdateien weitere Store Sources definieren, die wiederum weitere globale Konfigurationsdateien enthalten können. Solche Ketten sind nicht erlaubt, nur globale Konfigurationsdateien auf der ersten Ebene werden berücksichtigt.

`ENTITIES`

Entity-Konfigurationsdateien werden beim Start in der Reihenfolge der Store Sources gelesen. Zuerst werden alle DEFAULTS gelesen und in der Reihenfolge der Store Sources zusammengeführt. Dann werden die INSTANCES in der Reihenfolge der Store Sources erstellt. Wenn eine Instanz in mehreren Store Sources existiert, wird nur die erste erstellt da eine Instanz nur einmal existieren kann. Duplikate werden als Fehler geloggt. Zuletzt werden alle OVERRIDES auf die Instanzen in der Reihenfolge der Store Sources angewendet.

`VALUES`

Value-Konfigurationsdateien werden beim Start in der Reihenfolge der Store Sources gelesen. Wenn eine Pfad in mehreren Store Sources existiert, gewinnt die später definierte Store Source. Wenn die Anwendung einen Value mit einem bestimmten Pfad schreiben will, werden die Store Sources in umgekehrter Reihenfolge nach der ersten Quelle durchsucht, die für Values mit dem angegebenen Präfix beschreibbar ist. Wenn also mehr als eine Quelle für den angegebene Pfad in Frage kommt, gewinnt diejenige, die später definiert wurde.

`RESOURCES`

Ressourcen werden nur bei Bedarf abgerufen. Wenn die Anwendung eine Ressource mit einem bestimmten Pfad lesen will, werden die Store Sources in umgekehrter Reihenfolge auf das Vorhandensein dieses Pfades überprüft. Wenn also ein Pfad in mehr als einer Store Source vorhanden ist, gewinnt die später definierte Store Source. Wenn die Anwendung eine Ressource mit einem bestimmten Pfad schreiben will, werden die Store Sources in umgekehrter Reihenfolge nach der ersten Quelle durchsucht, die für Ressourcen mit dem angegebenen Präfix beschreibbar ist. Wenn also mehr als eine Quelle für die angegebene Ressource in Frage kommt, gewinnt diejenige, die später definiert wurde.

Beispiele

Entity Instanzen aus lokaler ZIP-Datei


store:
  sources:
  - type: FS
    content: INSTANCES
    src: /path/to.zip

ZIP


services/
  foo.yml
  bar.yml

GeoPackages aus entfernter ZIP-Datei


store:
  sources:
  - type: HTTP
    content: RESOURCES
    prefix: features
    src: https://example.org/path/to.zip

ZIP


foo.gpkg
bar.gpkg

Unterverzeichnis aus GitHub Repository


store:
  sources:
  - type: GITHUB
    src: org/repo
    archiveRoot: /path/to/store

Datenverzeichnis mit altem Store-Layout

Kann benutzt werden falls das alte Layout weiterhin mit v4 verwendet werden soll.


store:
  sources:
  - type: FS
    content: MULTI
    src: /old/data
    parts:
    - content: CFG
      src: cfg.yml
    - content: ENTITIES
      src: store
    - content: RESOURCES
      src: api-resources
    - content: RESOURCES
      src: api-resources/resources
      prefix: api-resources
    - content: RESOURCES
      src: store/resources
      mode: RO
    - content: RESOURCES
      src: cache/tiles
      prefix: tiles
    - content: RESOURCES
      src: cache/tiles3d
      prefix: tiles3d
    - content: RESOURCES
      src: proj
      prefix: proj
    - content: RESOURCES
      src: templates/html
      prefix: html/templates

# Store (neu)

# Optionen

# Store Sources

# Optionen

# Source Types

# FS

# S3

# HTTP

# GITHUB

# GITLAB

# GITEA

# Content Types

# ALL

# CFG

# ENTITIES

# INSTANCES*

# DEFAULTS

# OVERRIDES

# VALUES

# RESOURCES

# MULTI

# Reihenfolge

# CFG

# ENTITIES

# VALUES

# RESOURCES

# Beispiele

# Entity Instanzen aus lokaler ZIP-Datei

# GeoPackages aus entfernter ZIP-Datei

# Unterverzeichnis aus GitHub Repository

# Datenverzeichnis mit altem Store-Layout

Store (neu)

Optionen

Store Sources

Optionen

Source Types

`FS`

`S3`

`HTTP`

`GITHUB`

`GITLAB`

`GITEA`

Content Types

`ALL`

`CFG`

`ENTITIES`

`INSTANCES`*

`DEFAULTS`

`OVERRIDES`

`VALUES`

`RESOURCES`

`MULTI`

Reihenfolge

`CFG`

`ENTITIES`

`VALUES`

`RESOURCES`

Beispiele

Entity Instanzen aus lokaler ZIP-Datei

GeoPackages aus entfernter ZIP-Datei

Unterverzeichnis aus GitHub Repository

Datenverzeichnis mit altem Store-Layout