Masterportal konfigurieren: Praxis-Guide fuer Kommunen

Wer ein kommunales Geoportal auf Masterportal-Basis aufsetzt oder modernisiert, steht schnell vor denselben Fragen: Welche Datei steuert was, wo liegen die typischen Fehler, und wie bleibt das System auch nach Updates stabil betreibbar? Das Masterportal selbst positioniert sich klar als clientseitiger Open-Source-Baukasten fuer Geoportale. [1]

Dieser Leitfaden fokussiert deshalb auf die praktische Konfiguration in echten Verwaltungsprojekten: von der neuen Struktur ab Version 3 ueber Layer- und Styling-Logik bis zu CORS, Reverse Proxy und Release-Strategie.

Architektur und der Paradigmenwechsel zu Version 3

Mit Version 3 wurden die Konfigurationsstrukturen des Masterportals grundlegend vereinheitlicht. Fuer Migrationsprojekte ist vor allem wichtig: bestehende V2-Konfigurationen muessen auf die neue Logik umgestellt werden, dafuer gibt es ein offizielles Migrationsvorgehen. [2]

In der Praxis bedeutet das fuer Kommunen:

Vor einer produktiven Migration immer einen Testserver aufsetzen.
Alte und neue Konfigurationsdateien parallel vergleichen.
Erst nach fachlichem Abnahmetest umschalten (Suche, Druck, GFI, Fachlayer).

Die Konfigurationsmatrix: Globale und portalspezifische Steuerung

Die eigentliche Staerke des Masterportals liegt in der Trennung zwischen globalen Dienstedefinitionen und portalbezogener UI-Steuerung. So koennen mehrere Fachportale auf derselben Dienstebasis aufsetzen.

`config.js` als Routing-Zentrale

config.js ist der Einstiegspunkt des Portals und referenziert die eigentlichen Konfigurationsdateien. [3]

Typische Schluessel in Projekten:

layerConf: Pfad zur services.json.
restConf: Pfad zur rest-services.json.
styleConf: Pfad zur style.json.
proxyHost: optionaler Proxy-Endpunkt fuer nicht CORS-faehige Dienste.
addons: Registrierung eigener Erweiterungen.

Beispiel:

const config = {
  layerConf: "./resources/services.json",
  restConf: "./resources/rest-services.json",
  styleConf: "./resources/style.json",
  proxyHost: "https://geo.example.de/proxy/",
  addons: ["mein-fachmodul"]
};

`config.json` fuer Oberflaeche und Themenbaum

In der config.json werden Bedienkonzept und Themenstruktur definiert, vor allem ueber portalConfig und layerConfig. [4]

Relevante Praxispunkte:

Menues und Werkzeuge nur aktivieren, wenn sie fachlich gebraucht werden.
Suchdienste sauber mit IDs an vorhandene REST-Services koppeln.
Themenbaeume nicht technisch, sondern nutzerzentriert schneiden.

Die Datenbasis: `services.json` und `rest-services.json`

services.json definiert die eigentlichen Geo- und Fachdienste (z. B. WMS, WFS, OAF, SensorThings) inklusive URLs und Layer-Metadaten. [5]

rest-services.json verwaltet Zusatzdienste wie Druck, Gazetteer oder Kataloge und wird von Modulen zentral referenziert. [6]

Typischer Fehler: JSON-Syntaxprobleme. Ein fehlendes Komma oder ein ungueltiger String bricht das Laden des Portals oft sofort ab.

Praxis-Tipp: Fuer Teams ohne taegliche JSON-Routine reduziert ein grafischer Dienstemanager die Fehlerquote deutlich. [14]

Fortgeschrittene Strukturierung: Grouped Layers im Themenbaum

Grouped Layers helfen, mehrere technische Layer als eine fachliche Einheit zu praesentieren. Das ist gerade in kommunalen Dashboards hilfreich, wenn WMS, WFS oder Sensordaten gemeinsam angezeigt werden sollen. [7]

Beispiel fuer eine fachliche Gruppierung:

{
  "id": "umwelt-dashboard",
  "name": "Umwelt-Dashboard",
  "typ": "GROUP",
  "children": [
    { "id": "luftqualitaet_wms" },
    { "id": "messstationen_wfs" },
    { "id": "regenpegel_sensor" }
  ]
}

Wichtig ist, die Gruppe aus Nutzersicht zu benennen und nicht nach internen Servernamen.

Vektordaten-Styling und die Logik der `style.json`

Bei WFS-, GeoJSON- oder Sensor-Layern entscheidet die style.json ueber die Darstellung im Client. Die Regelreihenfolge ist kritisch: die erste passende Regel gewinnt. [8]

Wenn keine Regel greift, wirkt ein Layer schnell “leer”, obwohl Daten vorhanden sind. Ein Fallback-Style am Ende der Regeln ist daher Pflicht.

{
  "styleId": "baumkataster",
  "rules": [
    {
      "conditions": { "attr": "zustand", "operator": "==", "value": "kritisch" },
      "style": { "circleFillColor": [220, 38, 38, 0.9], "circleRadius": 6 }
    },
    {
      "style": { "circleFillColor": [22, 163, 74, 0.85], "circleRadius": 5 }
    }
  ]
}

Integration moderner OGC-Schnittstellen (OAF und SensorThings)

OGC API Features ist der moderne, API-orientierte Nachfolger klassischer Feature-Schnittstellen und fuer webnahe Architekturen in Kommunen zunehmend relevant. [9] [10]

Im Masterportal wird OAF als eigener Servicetyp eingebunden. Auch SensorThings kann direkt in der Dienstekonfiguration genutzt werden. [5]

Praxisnutzen:

Klare REST-Endpunkte statt komplexer KVP-Requests.
Gute Eignung fuer Dashboards mit haeufig aktualisierten Daten.
Sauberere Trennung zwischen Anzeige, Suche und Download.

Corporate Identity und UI-Anpassungen

Fuer kommunale Portale ist CI-Konformitaet kein Bonus, sondern Standardanforderung. In der Praxis beginnt das bei Portalname, Branding und konsistenten Farben und endet bei eindeutigem Wording in Menues, Suchplatzhaltern und Tool-Hinweisen.

Technisch hat sich bewaehrt:

Markenfarben zentral in Styles/SASS-Variablen verwalten.
Icons und Tooltexte auf die Verwaltungszielgruppe abstimmen.
UI-Aenderungen in einem eigenen Theme-Layer kapseln, um Updates sauber einspielen zu koennen.

Eigene Fachanwendungen als Add-ons integrieren

Wenn Standardtools nicht reichen, koennen eigene Vue-basierte Add-ons eingebunden werden. Der offizielle Workflow beschreibt Struktur und Einbindung ueber Add-on-Konfiguration und Modulregistrierung. [11]

Das ist in Projekten besonders hilfreich fuer:

Fachspezifische Workflows (z. B. Bauleitplanung, Starkregen, Liegenschaftsauskunft).
Eigene Formulare mit Georeferenz.
Angepasste Exporte und interne Prüf- oder Freigabeprozesse.

Betrieb, Troubleshooting und Performance-Optimierung

CORS-Restriktionen und Nginx Reverse Proxy

Browser-CORS ist ein Standardproblem, wenn Dienste auf anderen Hosts liegen. Die Masterportal-Dokumentation beschreibt Proxy-Mechanismen und verweist zugleich auf den sauberen CORS-Weg direkt an den Services. [15]

Wenn ein Reverse Proxy noetig ist, ist Nginx eine bewaehrte Option fuer Routing und Header-Handling. [12]

WebGL-Rendering fuer datenintensive Layer

Bei grossen Punktmengen helfen in der layerConfig WebGL-orientierte Renderpfade und passende Layeroptionen, um Browser-Rendering auf Nutzerniveau fluessig zu halten. [4]

Typische Massnahmen:

Initial sichtbare Layer auf das Noetige begrenzen.
Massstabsabhaengige Sichtbarkeit definieren.
Feature-Mengen filtern und serverseitig vorbegrenzen.
Karte initial ueber Capabilities-Extent bzw. sinnvolle Ausdehnung starten.

Release Management und LTS-Strategien fuer Kommunen

Kommunale Betriebsprozesse brauchen planbare Release-Zyklen. Fuer Masterportal sind LTS-Staende deshalb ein sinnvoller Anker fuer Produktivumgebungen; ein Beispiel ist die benoetigte Langzeitpflege rund um 3.15.2 LTS. [13]

Empfohlener Ablauf:

Entwicklung und Tests in separaten Umgebungen.
Definierter Freigabeprozess vor Produktion.
Klare Rollback-Strategie fuer kritische Aenderungen.
Quartalsweiser Review von Sicherheits- und Minor-Updates.

Checkliste fuer die Praxis

Sind config.js, config.json, services.json und rest-services.json konsistent verknuepft?
Sind Suchdienste, Druckdienste und Metadatenquellen fachlich getestet?
Gibt es fuer jeden kritischen Vektorlayer einen Fallback in style.json?
Ist CORS an den Diensten sauber konfiguriert oder ein kontrollierter Proxy vorhanden?
Sind Add-ons updatefest gekapselt und dokumentiert?
Laeuft der Betrieb auf einem klar definierten LTS-/Releasepfad?

FAQ

Welche Datei passe ich zuerst an?

Meistens config.js, weil dort die Referenzen auf alle weiteren Konfigurationsdateien gesetzt werden. Danach folgen config.json (UI/Themenbaum) und services.json (Dienste).

Warum sehe ich Layer im Baum, aber keine Objekte?

Haeufigster Grund ist nicht der Dienst selbst, sondern Konfiguration: falsche Layer-ID, unpassender Massstabsbereich oder fehlender Fallback in style.json.

Wann lohnt sich OGC API Features statt WFS?

Wenn Sie API-orientiert arbeiten, viele Web-Clients anbinden oder moderne Filter-/Paging-Muster brauchen, ist OAF in vielen Szenarien die robustere Wahl.

Sollte ich den Proxy dauerhaft nutzen?

Nur, wenn es betrieblich noetig ist. Sauber gesetzte CORS-Header direkt am Dienst sind in der Regel die langfristig wartbarere Loesung.

Quellen

[1] Masterportal
[2] Migrate Config to v3 - Masterportal Docs
[3] config.js - Masterportal Docs
[4] config.json - Masterportal Docs
[5] services.json - Masterportal Docs
[6] rest-services.json.md - Masterportal GitLab
[7] Grouped Layers - Masterportal Docs
[8] style.json - Masterportal Docs
[9] OGC API Features Standard
[10] Features - Overview - OGC API
[11] Vue.js Add-ons - Masterportal Docs
[12] NGINX Reverse Proxy
[13] Masterportal Version 3.15.2 (LTS) veroeffentlicht
[14] Dienstemanager (Fork)
[15] Proxy - Masterportal Docs

Masterportal konfigurieren: Praxis-Leitfaden fuer kommunale Geoportale