Configuration

Configuration files

The following configuration files are processed by map.apps:

  1. WEB-INF/classes/default-application.properties (DO NOT EDIT)
    This file contains all configuration options of map.apps with their default values.

  2. WEB-INF/classes/custom-application.properties
    If a change to the working directory (data.directory.location) is required, the change has to be made in this file. Any further changes have to be made in the following file.

  3. [data.directory.location]/application.properties
    Editing this file is the recommended way to make configuration changes. The default working directory (data.directory.location) of map.apps is ${user.home}/.mapapps. The file is not created automatically, so the file WEB-INF/classes/application.properties can be used as a template. It is recommended to leave only the settings that have been changed in the file.

The format of the configuration files must correspond to the Java .properties file format, which is described at https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html.

Sample .properties file
# The files have to be UTF-8 encoded, otherwise special characters can lead to errors!
# A safe method is to use Unicode syntax e.g: รค = \u00E4 (see http://0xcc.net/jsescape/)

# comments use the hash sign

# the syntax is:
key = value

# a value can reference another key
key1 = http://${key.with.server}/test

If the property configuration.watch.changes is enabled, any changes of the file ${data.directory.location}/application.properties triggers an internal reloading of the application settings. Changes of other configuration files are considered, too. Invalid settings might prevent a successful internal reload. A manual restart of the web application is required to repair this failure.

If the property configuration.watch.changes is disabled, restarting the web application is necessary (you might also restart the Tomcat server).

Configuration parameters

This section describes the parameters that most often need to be changed in a standard installation. Further parameters are described in comments in the file WEB-INF/classes/default-application.properties.

data.directory.location

This parameter defines the working directory in which map.apps data is stored locally. The default value is data.directory.location=$\{user.home\}/.mapapps. In case the Tomcat server is running as a Windows service, the .mapapps directory is located in the user directory of the Tomcat user who started the service. Path separators must be specified as either / or \\.

Tomcat User
If no Tomcat user has been created, the Tomcat server runs with the system user (not recommended!). In this case the directory is created under the following path: C:/Windows/System32/config/systemprofile/.mapapps.

A divergent map.apps data directory can be configured in the file WEB-INF/classes/custom-application.properties.

configuration.watch.changes

This parameter enables monitoring of the ${data.directory.location}/application.properties file. This allows configuration settings to be changed without restarting the web application. The default value is true. The configuration file must be present when the web application is started so that it can be monitored.

client.config.defaultLocale

map.apps supports German and English in the user interface by default. The language setting of the browser is recognized and map.apps is started in the corresponding language. If the language in the browser is neither German nor English, the value of this parameter is used.

client.config.supportedLocales

This parameter defines the languages supported by map.apps. If a language extension is installed, the new language must be added here. The default value is en,de. In GitHub there is a tutorial for adding more languages .

client.config.productname

In the default layout of map.apps, the upper left corner shows the text "map.apps". This text can be changed by setting this parameter.

client.config.requestTimeout

This parameter defines the global timeout value of all requests using esri/ct.request that do not their own timeout value.

Database connection

This section describes the configuration properties for the database connection. By default, map.apps uses the HSQL database which is included in map.apps. It is not recommended to use the HSQL database in productive systems.

If you run multiple instances of map.apps in parallel, you cannot use the same HSQL database. Change the parameter data.directory.location of every instance accordingly.

Change the database connection by editing the following properties:

db.use

This parameter specifies whether a direct database connection (JDBC) or a container-managed database connection (JNDI) is to be established. Allowed values are jndi or jdbc. The default value is jdbc, which means that no container configuration is necessary. JNDI is recommended if there are several web applications in the container (such as Apache Tomcat) accessing the same database (see also Apache Tomcat JNDI documentation ).

db.type

Vendor-specific type of the database system used. This is used internally to generate correct and optimized database queries. The default value is hsqldb. Values for other database systems can be found in the following table.

db.hibernate.schemaUpdate

Defines if and how the database schema is updated. Possible values are validate and update. Default value is update.

Attribute values for different database systems

Database Type Example-URL

PostgreSQL

postgresql

jdbc:postgresql://localhost:5432/mapapps

Oracle Database

oracle

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

MS-SQL Server

sqlserver

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

HSQLDB

hsqldb

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

Direct database connection (JDBC)

To setup a direct database connection, the following parameters have to be set in addition to the preceding attributes:

db.jdbc.url

The URL of the JDBC database connection. Its value depends on the database system in use (see preceding table). Default value: jdbc:hsqldb:file:$\{data.directory.location\}/storage/db;shutdown=true

db.jdbc.username

Username of the database user. Default value: sa

db.jdbc.password

Password of the database user.

db.jdbc.maxActiveConnections

Maximum number of active database connections in the deployed Connection Pool. Default value: 50

db.jdbc.minActiveConnections

Minimum number of active database connections in the deployed Connection Pool. Default value: 1

Copy the corresponding JDBC driver to the folder %MAPAPPS%/WEB-INF/lib when using a JDBC connection.

Container managed database connection (JNDI)

To configure a database connection through JNDI, the following parameter has to be configured in addition to the three attributes listed preceding:

db.jndi.name

The JNDI name to use by the container to query the database. The default value is java:comp/env/jdbc/mapapps.

Additionally the following steps have to be performed:

  1. Open the file server.xml which is located in the conf directory of the Apache Tomcat installation folder.

  2. Add the following entry to the <GlobalNamingResources> element:

    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" />

    In this example this element is adjusted to the PostgreSQL database. If you are using a different database than PostgreSQL, you have to adjust the attributes driverClassName and URL. The preceding table lists the driverClassNames and example database URLs for various databases.

  3. Adjust the values of the attributes username and password to the conditions in your system.

  4. Copy the JAR file that contains the JDBC driver for your database to the lib directory of your Apache Tomcat.

  5. Open the file context.xml from the META-INF directory of the map.apps web application. To enable the element <ResourceLink name="jdbc/mapapps" global="mapappsdb" type="javax.sql.DataSource"/> remove the enclosing comment tags.

  6. Save all modified files and restart Apache Tomcat.

If new settings are not applied correctly or if you experience any errors, check the content of the file conf/Catalina/localhost/ct-mapapps-webapp-4.11.1.xml as this file might be out of date. If so, delete that file. It is regenerated with the correct settings during the next start of the Tomcat server.

Container managed database connection with HikariCP (JNDI)

We recommend the usage of the Database Connection Pool HikariCP.

The configuration inside the server.xml looks then like:

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" />

Next to the database driver it is required to install the following libraries inside the Tomcat lib directory:

PostgreSQL maintenance

So-called blobs are used to save bundles or report templates. Depending on the number and size of the uploaded files, this can result in a high amount of storage space being used over time because the blobs are not removed correctly in PostgreSQL. PostgreSQL recommends the following strategies to solve this problem:

  • Run the vacuumlo tool provided with PostgreSQL on a regular basis. The tool removes data that is no longer used.

  • Alternatively, database triggers can be registered that correctly delete the corresponding data when updating or deleting rows. The file postgres-blob-cleanup-trigger.sql in the resources/sql directory of the download file contains the SQL statements required to register the triggers.

Default URLs

Secured Access
It is recommended to access external URLs using the HTTPS protocol.
printtask.service.url

URL for the ArcGIS for Server Print Task. The value is used by the printing bundle and the report service. A print task configured as synchronous is required by the reporting service. If another configuration is needed for the report service, the parameter reporting.printtask.service.url can be used.

esri.api.arcgisPortalUrl

Defines the base URL of ArcGIS Online or the central ArcGIS Portal installation for example:

https://www.myserver.de/portal

The default value is: //www.arcgis.com.

geometry.service.url

URL of the ArcGIS for Server Geometry Service.

locator.service.url

URL of an Esri locator service used by the bundle locator-store by default.

Security settings

map.apps includes an integrated security mechanism on delivery. All possibilities and options for security settings, user administration and protection are summarized in security.

Proxy settings

proxy.allowedServerUrls

map.apps provides an integrated proxy servlet. This is needed, because direct access to other resources is prohibited within JavaScript due to security restrictions. This property contains a list of URLs that are allowed to be accessed by the proxy servlet.

The configuration uses the following syntax:

Each entry must be followed by a ;. If several lines are to be used, a \ must follow at the end of every line (except the last one). No spaces are allowed after the \.

Within url-expression, * might be used as placeholders:

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

Defines that access to any subdomain of test.de and the path '/arcgis' is allowed. Add a /** at the end of the expression to allow all deeper URLs if wildcards are used. The * wildcard does not include the /. The ** wildcard contains the /.

https:/test.de/arcgis

If no placeholders are used, it is assumed that all redirects to URLs beginning with the expression are allowed.

The following property expressions are available:

  • user:<username>
    The username for HTTP basic authentication

  • pw:<password>
    The password for HTTP basic authentication

  • token:<token>
    A long-lived ArcGIS Server Token

  • followRedirects:<true|false>
    Defines if forwarding is tracked by the proxy (default is false)

  • trusted:<true|false>
    If a URL is marked as trusted, this means that cookies and Authorization HTTP headers are forwarded through the proxy.

  • There is an old syntax with implicit semantics besides the property-expression expressions:

  • <url>,<token> means append token

  • <url>,<username>,<password> means HTTP basic required

  • <url>,* means trusted

It is recommended to use the new property-expression syntax.

Configure URLs as exactly as possible to reduce security risks!

Samples:

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

  • HTTP + HTTPS URL (but only default ports): *://sampleserver1.arcgisonline.com/arcgis/rest/services/**;

  • HTTP + HTTPS URLs (with custom ports): *://sampleserver1.arcgisonline.com:*/arcgis/rest/services/**;

  • add arcgis server token: http://myserver.mycompany.com/arcgis/rest/services,token:xyz123;

  • define username/password for HTTP basic authentication: http://test.de/path/**,user:test,pw:testtest;

  • define that cookies and authorization headers are forwarded: http://test.de/path/**,trusted:true;
proxy.allowUnsafeServerUrls

Enables unsecure values in the parameter proxy.allowedServerUrls. The default value is false.

The following configurations are considered unsafe:

  • "localhost" forwards might expose unwanted access to service on the host server over the proxy

  • protocol only definitions, like "http://" it allows uncontrolled network access over the proxy

proxy.use.rules

Defines rules for proxy access based on hostnames. It provides more fine-grained control over which requests are routed through a proxy page.

Example:

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

That means:

sample1.mapapps.de is requrested over default "/proxy" ,

sample2.mapapps.de is requested over own proxy page "/proxyPage".

CORS settings

The following settings are required for Cross Origin Request support.

If you have configured a proxy rule, map.apps continues to use the proxy. Otherwise, requests are made with the assumption that CORS is supported.

cors.allowed.origins

List of base URLs of websites which are allowed to access the service interface of map.apps with CORS (* can be used as wildcard).

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

Example (with wildcards): http*://*.mydomain.net:*

Allows access from any subdomain of mydomain.net via http and https from any port.

proxy.cors.trustedServers

List of URLs for backend services for which the transfer of security-critical information with CORS is activated (for example cookies and authorization headers)

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

This setting is not applied to apps prior to version 4.6.0. See proxy.cors.enabledServers.

CORS settings for apps prior to version 4.6.0
proxy.cors.enabledServers

List of URLs for backend services that support CORS.

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

In addition, the transfer of security-critical information (for example cookies) can be activated at this point.

Example: https://myserver1.com|true

This setting is not used for apps of version 4.6.0 or later. See proxy.cors.trustedServers.

Logging of errors and messages

The following logging configuration options can be used:

logging.logger.level

This parameter defines the level of detail for the logging. Possible values are: TRACE, DEBUG, INFO, WARN, ERROR. The default value is INFO.

logging.output.location (Deprecated since 4.9.1)

Use logging.file.location instead.

logging.file.location

This parameter defines the log file location. The default value is ${catalina.base}/logs. This is the folder of the tomcat log files. It is possible to create the map.apps log files in the working directory of map.apps by using the value ${data.directory.location}/logs.

logging.file.prefix

This parameter defines the name of the log files. The default value is ct-mapapps-webapp.It is possible to use the value ${webcontext.name} which means that the log files are named like the URL context path of the map.apps installation for example mapapps.

Additional logging options are described in the default-application.properties file, for example to enable or disable logging into the console, into files, and GELF logging.