Konfiguration

Konfigurationsdateien

Folgende Konfigurationsdateien werden von map.apps verarbeitet:

  • WEB-INF/classes/default-application.properties (NICHT EDITIEREN)
    In dieser Datei befinden sich alle Konfigurationsoptionen von map.apps mit ihren Standardwerten.

  • WEB-INF/classes/custom-application.properties
    Wenn eine Änderung des Arbeitsverzeichnisses (data.directory.location) nötig ist, muss die Änderung in dieser Datei erfolgen. Alle weiteren Anpassungen erfolgen in der nachfolgenden Datei.

  • [data.directory.location]/application.properties
    Nehmen Sie Änderungen an der Konfiguration durch das Bearbeiten dieser Datei vor.
    Das Arbeitsverzeichnis (data.directory.location) von map.apps ist in der Standardinstallation das Verzeichnis ${user.home}/.mapapps. Die Datei wird nicht automatisch erstellt, daher kann als Vorlage die Datei WEB-INF/classes/application.properties dienen. Belassen Sie nur die Einstellungen in der Datei, die geändert wurden.

Das Format der Konfigurationsdateien muss dem Java Properties Dateiformat entsprechen.

Beispiel Java Properties Datei
# Die Dateien müssen UTF-8 kodiert sein, sonst können Umlaute zu Fehlern führen!
# Am sichersten ist die Kodierung von Umlauten in Unicode-Syntax z.B: ä = \u00E4 (vgl. http://0xcc.net/jsescape/)

# Kommentare erfolgen mit Raute

# die Syntax ist:
key = value

# Eine Value kann einen anderen Key referenzieren
key1 = http://${key.with.server}/test

Wenn die Einstellung configuration.watch.changes aktiviert ist (was standardmäßig der Fall ist), führt jede Änderung in der Datei ${data.directory.location}/application.properties zu einem erneuten Einlesen der Konfigurationseinstellungen. Änderungen in anderen Konfigurationsdateien werden dabei berücksichtigt. Fehlerhafte Einstellungen können ein erfolgreiches Einlesen verhindern. Ist dies der Fall, ist ein Neustart der Web-Applikation notwendig.

Ist die Konfiguration configuration.watch.changes nicht aktiviert, ist nach der Änderung einer der Konfigurationsdateien ein manueller Neustart der Web-Applikation erforderlich (alternativ können Sie den kompletten Tomcat Server neu starten).

Konfigurationsparameter

In diesem Abschnitt werden die Parameter beschrieben, die am häufigsten in einer Standardinstallation verändert werden müssen. Weitere Parameter sind in der Datei WEB-INF/classes/default-application.properties in Kommentaren beschrieben.

data.directory.location

Dieser Parameter definiert das Arbeitsverzeichnis, in dem map.apps-Daten (z.B. eine HSQL-Datenbank) lokal gespeichert werden. Der Standardwert ist data.directory.location=$\{user.home\}/.mapapps. Für den Fall, dass der Tomcat-Server als Windows-Dienst betrieben wird, liegt das .mapapps Verzeichnis im Nutzerverzeichnis des Tomcat-Nutzers, der den Dienst gestartet hat. Pfad-Trenner müssen entweder als / oder \\ angegeben werden.

Tomcat Nutzer

Wenn kein Tomcat-Nutzer angelegt wurde, wird der Tomcat-Server mit dem Systemnutzer ausgeführt (nicht empfohlen). In diesem Fall wird das Verzeichnis unter folgendem Pfad angelegt: C:/Windows/System32/config/systemprofile/.mapapps.

Ein abweichendes map.apps Datenverzeichnis kann in der Datei WEB-INF/classes/custom-application.properties konfiguriert werden.

configuration.watch.changes

Dieser Parameter aktiviert die Überwachung der Datei ${data.directory.location}/application.properties. Dadurch können Konfigurationseinstellungen ohne Neustart der Web-Applikation geändert werden. Der Standardwert ist true. Die Konfigurationsdatei muss beim Starten der Web-Applikation vorhanden sein, damit sie überwacht werden kann.

client.config.defaultLocale

map.apps unterstützt standardmäßig die Sprachen Deutsch und Englisch. Die Spracheinstellung des Browsers wird erkannt und map.apps wird in der entsprechenden Sprache gestartet. Falls die Sprache im Browser weder Deutsch noch Englisch entspricht, wird der Wert dieses Parameters eingesetzt.

client.config.supportedLocales

Dieser Parameter definiert die von map.apps unterstützten Sprachen. Wird eine Spracherweiterung installiert, muss die neue Sprache ebenfalls hinterlegt werden. Der Standardwert ist en,de. In GitHub steht eine Anleitung zum Hinzufügen weiterer Sprachen bereit.

client.config.productname

Im Standardlayout wird oben links in der App-Übersicht, dem map.apps Manager und in den einzelnen Apps der Begriff "map.apps" angezeigt. Dieser Text kann mit diesem Parameter angepasst werden.

client.config.requestTimeout

Dieser Parameter definiert den globalen Timeout-Wert für alle Anfragen, die esri/ct.request verwenden und keinen eigenen Timeout-Wert definieren.

Datenbank-Anbindung

map.apps verwendet standardmäßig eine HSQL-Datenbank, die in der Auslieferung enthalten ist. Sie wird zu Testzwecken automatisch im Dateisystem erstellt und erfordert keine weitere Konfiguration. Verwenden Sie die HSQL-Datenbank nicht in produktiven Umgebungen.

HSQLDB

Mehrere parallele Installationen von map.apps können nicht auf dieselbe HSQL-Datenbank verweisen. Ändern Sie in diesem Fall für eine Instanz den Parameter data.directory.location.

Microsoft SQL Server

Setzen Sie bei Verwendung von Microsoft SQL Server bei der Anlage der Datenbank die Collation auf ein case-sensitives Format (zum Beispiel Latin1_General_CS_AS).

Zur Verwendung einer anderen Datenbank können Sie eine Verbindung durch Änderungen der folgenden Parameter herstellen:

db.use

Dieser Parameter gibt an, ob eine direkte Datenbankverbindung (JDBC) oder eine container-managed Datenbankverbindung (JNDI) aufgebaut wird. Erlaubte Werte sind jndi oder jdbc. Der Standardwert ist jdbc, da somit keine Container-Konfiguration notwendig ist. Verwenden Sie JDNI, wenn mehrere Webanwendungen im Container (z.B. Apache Tomcat) vorhanden sind, die auf dieselbe Datenbank zugreifen (siehe Apache Tomcat JNDI-Dokumentation ).

db.type

Herstellerspezifischer Typ des verwendeten Datenbanksystems. Dieser wird intern verwendet, um korrekte und optimierte Datenbankanfragen zu erzeugen. Der Standardwert ist hsqldb. Werte für andere Datenbanksysteme können der unten stehenden Tabelle entnommen werden.

db.hibernate.schemaUpdate

Definiert, ob und wie das Datenbankschema automatisch angepasst wird. Erlaubte Werte sind validate und update. Der Standardwert ist update.

Attribut-Werte für verschiedene Datenbanksysteme

Datenbank Typ Beispiel-URL

PostgreSQL

postgresql

jdbc:postgresql://localhost:5432/mapapps

Oracle Database

oracle

jdbc:oracle:thin:@myhost:1521:orcl

Microsoft SQL Server

sqlserver

jdbc:sqlserver://localhost:1433;databaseName=mapapps

HSQLDB

hsqldb

jdbc:hsqldb:file:$\{data.directory.location\}/storage/db;shutdown=true

Direkte Datenbankverbindung (JDBC)

Um eine direkte Datenbankverbindung zu nutzen, konfigurieren Sie zusätzlich zu den drei o.g. Parametern die folgenden Werte:

db.jdbc.url

Die JDBC Datenbankverbindungs-URL. Dieser Wert ist vom verwendeten Datenbanksystem abhängig (siehe oben stehende Tabelle). Standardwert: jdbc:hsqldb:file:$\{data.directory.location\}/storage/db;shutdown=true

db.jdbc.username

Nutzername des Datenbanknutzers. Standardwert: sa

db.jdbc.password

Passwort des Datenbanknutzers.

db.jdbc.maxActiveConnections

Maximale Anzahl aktiver Datenbankverbindungen im verwendeten Connection-Pool. Standardwert: 50

db.jdbc.minActiveConnections

Minimale Anzahl aktiver Datenbankverbindungen im verwendeten Connection-Pool. Standardwert: 1

Wenn eine JDBC-Verbindung verwendet wird, muss der für die Datenbank passende JDBC-Treiber in das Verzeichnis %MAPAPPS%/WEB-INF/lib kopiert werden.

Container-managed Datenbankverbindung (JNDI)

Um eine Datenbankverbindung über JNDI einzurichten, müssen zusätzlich zu den drei o.g. Parametern die folgenden Werte konfiguriert werden:

db.jndi.name

Der JNDI-Name, über den die Datenbank vom Container erfragt werden kann. Standardwert: java:comp/env/jdbc/mapapps.

Darüber hinaus sind folgende Schritte in der Konfiguration des Tomcats zu befolgen:

  1. Öffnen Sie die Datei server.xml, die sich im Verzeichnis conf des Apache Tomcat befindet.

  2. Fügen Sie zum Element <GlobalNamingResources> das folgende Element hinzu:

    server.xml
    <Resource name="mapappsdb" auth="Container"
      type="javax.sql.DataSource"
      maxTotal="50"
      maxIdle="1"
      maxWaitMillis="10000"
      defaultAutoCommit="false"
      username="postgres"
      password="postgres"
      driverClassName="org.postgresql.Driver"
      url="jdbc:postgresql://localhost:5432/mapapps" />

    Dieses Element ist beispielhaft auf die PostgreSQL-Datenbank angepasst. Wenn Sie eine andere Datenbank als PostgreSQL verwenden, passen Sie die Attribute driverClassName und URL an. In der oben stehenden Tabelle sind die Werte für die verschiedenen Datenbanken aufgeführt.

  3. Passen Sie die Attribute username und password des Elements an die Gegebenheiten in Ihrem System an.

  4. Kopieren Sie die JAR-Datei des von Ihnen verwendeten JDBC-Datenbanktreibers in das Verzeichnis lib des Apache Tomcat.

  5. Öffnen Sie die Datei context.xml im Verzeichnis META-INF der map.apps-Webanwendung und entfernen Sie die Kommentare um das Element <ResourceLink name="jdbc/mapapps" global="mapappsdb" type="javax.sql.DataSource"/>, um es zu aktivieren.

  6. Speichern Sie alle veränderten Dateien und starten Sie Apache Tomcat neu.

Falls die Einstellungen nicht wirksam sind oder Fehlermeldungen auftreten, überprüfen Sie den Inhalt der Datei conf/Catalina/localhost/ct-mapapps-webapp-4.12.3.xml oder löschen Sie diese. Sie wird beim nächsten Start der Webanwendung neu generiert.

Container-managed Datenbankverbindung (JNDI mit HikariCP)

Wir empfehlen die Verwendung des Datenbank Connection Pool HikariCP.

Die Konfiguration in der server.xml ändert sich dann wie folgt:

server.xml
<Resource name="mapappsdb" auth="Container"
        factory="com.zaxxer.hikari.HikariJNDIFactory"
        type="javax.sql.DataSource"
        minimumIdle="1"
        maximumPoolSize="50"
        connectionTimeout="10000"
        dataSourceClassName="org.postgresql.ds.PGSimpleDataSource"
        dataSource.url="jdbc:postgresql://localhost:5432/mapapps"
        dataSource.user="postgres"
        dataSource.password="postgres" />

Zusätzlich müssen neben dem Datenbanktreiber folgende Bibliotheken im Tomcat lib Verzeichnis ergänzt werden:

PostgreSQL Wartung

Um Bundles oder Report-Vorlagen zu speichern werden sog. Blobs verwendet. Je nach Anzahl und Größe der hochgeladenen Dateien kann es dadurch im Laufe der Zeit zu einem hohen Speicherplatzverbrauch kommen, da die Blobs in PostgreSQL nicht korrekt entfernt werden. PostgreSQL empfiehlt folgende Strategien zur Lösung des Problems:

  • Führen Sie regelmäßig das von PostgreSQL zur Verfügung gestellte vacuumlo Werkzeug aus. Das Werkzeug entfernt die nicht länger verwendeten Dateien.

  • Alternativ können Datenbank-Trigger registriert werden, die beim Update oder Löschen von Zeilen die dazugehörigen Daten korrekt löschen. In der Datei postgres-blob-cleanup-trigger.sql im Verzeichnis resources/sql der map.apps Auslieferung finden Sie die benötigten SQL-Statements zum Registrieren der Trigger.

Standard-URLs

Transportverschlüsselung
Verwenden Sie bei der Konfiguration externer URLs immer das HTTPS-Protokoll.
printtask.service.url

URL für den ArcGIS for Server Print Task. Der Wert wird vom printing Bundle und vom Report-Dienst verwendet. Es muss sich um einen synchron konfigurierten Task handeln. Über den Parameter reporting.printtask.service.url kann eine abweichende Konfiguration für den Report-Dienst festgelegt werden.

esri.api.arcgisPortalUrl

URL des verwendeten Portal for ArcGIS, z.B.:
https://www.myserver.de/portal
Standardmäßig wird ArcGIS Online verwendet: //www.arcgis.com.

geometry.service.url

URL des ArcGIS for Server Geometry Service.

locator.service.url

URL eines Esri Locator Services der standardmäßig vom Bundle locator-store verwendet wird.

Sicherheitseinstellungen

map.apps enthält bei der Auslieferung einen integrierten Sicherheitsmechanismus. Sämtliche Möglichkeiten und Optionen zu Sicherheitseinstellungen, Nutzerverwaltung und Absicherung sind in Sicherheit zusammengefasst.

Proxy-Einstellungen

proxy.allowedServerUrls

map.apps stellt einen integrierten Proxy bereit. Dieser wird benötigt, weil direkter Zugang zu anderen Ressourcen aufgrund von Sicherheitsbeschränkungen innerhalb von JavaScript untersagt ist. Dieser Parameter enthält eine Liste von URLs, auf die der Proxy weiterleiten darf.

Die Konfiguration nutzt folgende Syntax:

<url-expression>[,<property-expression>];

Nach jedem Eintrag muss ein ; folgen. Um mehrere Zeilen zu nutzen, ergänzen Sie am Ende jeder Zeile (außer der letzten) ein \. Nach dem \ dürfen keine Leerzeichen folgen.

Innerhalb von url-expression dürfen * als Platzhalter verwendet werden:

https://*.test.de/arcgis/**

Definiert, dass Zugriffe auf jede Subdomäne von test.de und dem Pfad /arcgis erlaubt sind. Ergänzen Sie am Ende des Ausdrucks ein /**, damit alle tieferen URLs erlaubt sind wenn Platzhalter verwendet werden. Der * Platzhalter beinhaltet das / nicht. Der ** Platzhalter beinhaltet das /.

https:/test.de/arcgis

Wenn keine Platzhalter verwendet werden, wird angenommen, dass alle Weiterleitungen an URLs erlaubt sind, die mit dem Ausdruck beginnen.

Folgende property-expressions gibt es:

  • user:<username>
    Der Nutzername für HTTP basic Authentifizierung

  • pw:<password>
    Das Password für HTTP basic Authentifizierung

  • token:<token>
    Ein lang lebendes ArcGIS Server Token

  • followRedirects:<true|false>
    Definiert ob Weiterleitungen vom Proxy verfolgt werden (Standard ist false)

  • trusted:<true|false>
    Wenn eine URL als trusted markiert ist, bedeutet dies, dass Cookies und Authorization HTTP-Header über den Proxy weitergeleitet werden.

Konfigurieren Sie URLs immer so exakt wie möglich, um Sicherheitsrisiken zu vermeiden.

Beispiele:

  • Exakte URL: http://sampleserver1.arcgisonline.com/arcgis/rest/services/**;

  • HTTP + HTTPS URL (Aber nur mit Standardports 80/443): *://sampleserver1.arcgisonline.com/arcgis/rest/services/**;

  • HTTP + HTTPS URLs (Egal an welchem Port): *://sampleserver1.arcgisonline.com:*/arcgis/rest/services/**;

  • Arcgis Server Token ergänzen http://myserver.mycompany.com/arcgis/rest/services,token:xyz123;

  • Nutzername und Password für http basic Authentication vordefinieren http://test.de/path/**,user:test,pw:testtest;

  • Erlauben, dass Cookies and Authorization-Header weitergeleitet werden http://test.de/path/**,trusted:true;
proxy.allowUnsafeServerUrls

Aktiviert unsichere Werte in dem Parameter proxy.allowedServerUrls. Der Standardwert ist false.

Folgende Konfigurationen werden als unsicher betrachtet:

  • localhost Weiterleitungen. Dies würde die externe Verwendung von localhost ermöglichen.

  • Konfigurationen, die nur das Protokoll beinhalten z.B: http://. Dies würde den Zugriff auf alle URLs über den Proxy erlauben.

proxy.use.rules

Definiert Regeln für den Proxy-Zugriff abhängig von den angefragten Hostnamen. Dies ermöglicht die Kontrolle darüber, welche Requests über eine bestimmte Proxy-Seite geleitet werden.

Beispiel:
proxy.use.rules=sample1.mapapps.de,sample2.mapapps.de|/proxyPage

Bedeutung:
sample1.mapapps.de wird über die Standardproxyseite /proxy geleitet,
sample2.mapapps.de wird über eine eigene Proxyseite /proxyPage geleitet.

CORS-Einstellungen

Diese Einstellungen werden benötigt, um Cross Origin Requests zu ermöglichen.

map.apps geht davon aus, dass angefragte Webdienste CORS unterstützen. Falls eine Proxy Rule konfiguriert wurde, wird map.apps diese weiterhin verwenden. In allen anderen Fällen werden Anfragen mit der Annahme gemacht, dass CORS unterstützt wird.

cors.allowed.origins

Liste von Basis-URLs von Webseiten, die per CORS auf die angebotenen Serviceschnittstellen zugreifen dürfen (* kann als Platzhalter genutzt werden).

Beispiel: http://mydomain.net,http://otherdomain.de

Beispiel (mit Wildcards): http*://*.mydomain.net:*

Erlaubt den Zugriff von jeder Subdomäne von mydomain.net via http and https von jedem Port.

proxy.cors.trustedServers

Liste von URLs zu Backenddiensten, für die die Übergabe von sicherheitskritischen Informationen mittels CORS aktiviert wird (z.B. Cookies und Autorisierungs-Header)

Example: https://myserver1.com,http://myserver2.com

Diese Einstellung wird nicht für Apps vor Version 4.6.0 angewandt. Siehe proxy.cors.enabledServers.

CORS Einstellungen für Apps vor Version 4.6.0
proxy.cors.enabledServers

Liste von URLs zu Backenddiensten, die CORS unterstützen.

Beispiel: https://myserver1.com,http://myserver2.com

Außerdem kann an dieser Stelle die Übergabe von sicherheitskritischen Informationen aktiviert werden (z.B. Cookies).

Beispiel: https://myserver1.com|true

Diese Einstellung wird nicht für Apps der Version 4.6.0 oder höher angewandt. Siehe proxy.cors.trustedServers.

Logging von Fehlern und weiteren Meldungen

Es stehen folgende Konfigurationsparameter zur Anpassung des Loggings zur Verfügung:

logging.logger.level

Dieser Parameter definiert den Detailgrad des Logs. Mögliche Werte sind: TRACE, DEBUG, INFO, WARN, ERROR. Der Standardwert ist INFO.

logging.output.location (Ersetzt ab 4.9.1)

Verwenden Sie stattdessen logging.file.location.

logging.file.location

Dieser Parameter definiert den Ort, an dem die Log-Datei gespeichert wird. Der Standardwert ist ${catalina.base}/logs. Dies entspricht dem logs Verzeichnis des Tomcat. Um Log-Dateien im Arbeitsverzeichnis von map.apps zu erstellen, verwenden Sie den Wert ${data.directory.location}/logs.

logging.file.prefix

Dieser Parameter definiert den Namen der Log-Dateien. Der Standardwert ist ct-mapapps-webapp. Um den Log-Dateien den URL-Kontextpfad der map.apps-Installation voranzustellen (zum Beispiel mapapps), verwenden Sie den Wert ${webcontext.name}.

Weitere Logging-Parameter sind in der Datei default-application.properties beschrieben, z.B. zum Aktivieren oder Deaktivieren des Loggings in die Konsole, in Log-Dateien oder mittels GELF.