Konfiguration

Diese Seite beinhaltet die folgenden Abschnitte:

Konfigurationsdateien
Konfigurationsparameter

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
Das Bearbeiten dieser Datei ist der empfohlene Weg Konfigurationsänderungen vorzunehmen. 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. Es wird empfohlen nur die Einstellungen in der Datei zu belassen, die geändert wurden.

Das Format der Konfigurationsdateien muss dem Java .properties Dateiformat entsprechen, welches unter https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html beschrieben ist.

Beispiel .properties

# 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.

Datenbank-Anbindung

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

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.

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. JDNI wird empfohlen, 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, update, create, create-drop. Der Standardwert ist update.

Attribut-Werte für verschiedene Datenbanksysteme

Datenbank Typ driverClassName Beispiel-URL

Datenbank	Typ	driverClassName	Beispiel-URL
PostgreSQL	`postgresql`	`org.postgresql.Driver`	`jdbc:postgresql://localhost:5432/mapapps`
Oracle Database	`oracle`	`oracle.jdbc.OracleDriver`	`jdbc:oracle:thin:@myhost:1521:orcl`
MS-SQL Server	`sqlserver`	`com.microsoft.sqlserver.jdbc.SQLServerDriver`	`jdbc:sqlserver://localhost:1433;databaseName=mapapps`
HSQLDB	`hsqldb`	`org.hsqldb.jdbcDriver`	`jdbc:hsqldb:file:$\{data.directory.location\}/storage/db;shutdown=true`

PostgreSQL

postgresql

org.postgresql.Driver

jdbc:postgresql://localhost:5432/mapapps

Oracle Database

oracle

oracle.jdbc.OracleDriver

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

MS-SQL Server

sqlserver

com.microsoft.sqlserver.jdbc.SQLServerDriver

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

HSQLDB

hsqldb

org.hsqldb.jdbcDriver

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:mem:mapapps
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: 15

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:

Öffnen Sie die Datei server.xml, die sich im Verzeichnis conf des Apache Tomcat befindet.
Fügen Sie zum Element <GlobalNamingResources> das folgende Element hinzu:
server.xml
```
<Resource name="mapappsdb" auth="Container"
      type="javax.sql.DataSource"
      maxTotal="25"
      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. Bei Verwendung einer anderen Datenbank müssen die Attribute driverClassName und url angepasst werden. In der oben stehenden Tabelle sind die Werte für die verschiedenen Datenbanken aufgeführt.
Passen Sie die Attribute username und password des Elements an die Gegebenheiten in Ihrem System an.
Kopieren Sie die JAR-Datei des von Ihnen verwendeten JDBC-Datenbanktreibers in das Verzeichnis lib des Apache Tomcat oder das WEB-INF/lib-Verzeichnis der map.apps-Webanwendung.
Ö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.
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.9.2.xml oder löschen Sie diese. Sie wird beim nächsten Start der Webanwendung neu generiert.

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

Bei der Konfiguration externer URLs wird empfohlen, immer das https-Protokoll zu verwenden.

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.
Es gibt neben den property-expression-Ausdrücken eine alte Syntax mit implizierter Semantik:
<url>,<token> bedeutet Token weiterleiten
<url>,<username>,<password> bedeutet HTTP basic ergänzen
<url>,* bedeutet trusted

Es wird empfohlen die neue property-expression-Syntax zu verwenden.

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. Es ist möglich, die Log-Datei im Arbeitsverzeichnis von map.apps zu erzeugen, in dem der Wert ${data.directory.location}/logs verwendet wird.
logging.file.prefix: Dieser Parameter definiert den Namen der Log-Dateien. Der Standardwert ist ct-mapapps-webapp. Es ist möglich, den Wert ${webcontext.name} zu verwenden, wodurch die Log-Dateien mit dem Namen des Pfades in der URL beginnen - z.B. mapapps.

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.