Global configuration

Configuration files

The following configuration files are processed by map.apps:

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

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

  • [data.directory.location]/application.properties
    Make changes to the configuration by editing this file.
    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. Only leave the settings in the file that are changed.

The format of the configuration files must correspond to the Java Properties file format .

Sample Java 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, for example รค = \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).

Environment variables

You can also set the value of all configuration parameters using environment variables. These always override the values you set in the application.properties. This allows to easily customize the map.apps configuration in containerized environments, for example.

You need to translate the names of the configuration properties when using them as environment variables: Only use uppercase letters and replace any dot . by an underscore _.

Example: esri.api.arcgisPortalUrl becomes ESRI_API_ARCGISPORTALURL. This pattern applies to all configuration parameters.

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

Working directory in which map.apps data is stored locally.

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.

Tomcat User

If no Tomcat user is 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. Path separators must be specified as either / or \\.

Default: $\{user.home\}/.mapapps

configuration.watch.changes

Monitoring of the ${data.directory.location}/application.properties file.

If enabled, configuration settings can be changed without restarting the web application. The configuration file must be present when the web application is started so that it can be monitored.

Default: true

client.config.defaultLocale

Language settings.

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

client.config.supportedLocales

Languages supported by map.apps.

If a language extension is installed, the new language must be added to this property. In GitHub there is a tutorial for adding more languages .

Default: en,de

client.config.productname

Displayed product name.

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

Global timeout value for all requests that use esri/ct.request/apprt_request/request and do not define their own timeout value.

Database connection

map.apps uses an HSQL database by default, which is included in the release. It is automatically created in the file system for testing purposes and requires no further configuration.
Do not use the HSQL database in production environments.

HSQLDB

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

Microsoft SQL Server

When using Microsoft SQL Server, set the collation to a case-sensitive format (for example, Latin1_General_CS_AS) when creating the database.

Change the database connection by editing the following properties:

db.use

Specifies whether a direct database connection (JDBC) or a container-managed database connection (JNDI) is established.

Use JNDI if there are several web applications in the container (such as Apache Tomcat) accessing the same database (see also Apache Tomcat JNDI documentation ). Use JDBC which means that no container configuration is necessary.

Allowed values: jndi, jdbc
Default: jdbc

db.type

Vendor-specific type of the database system used.

This is used internally to generate correct and optimized database queries.

Allowed values:

Database Type Example-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

Default: hsqldb

db.hibernate.schemaUpdate

Defines if and how the database schema is updated.

Allowed values: validate and update
Default: update

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

URL of the JDBC database connection.

Its value depends on the database system in use (see preceding table).

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

db.jdbc.username

Username of the database user.

Default: sa

db.jdbc.password

Password of the database user.

db.jdbc.maxActiveConnections

Maximum number of active database connections in the deployed Connection Pool.

Default: 50

db.jdbc.minActiveConnections

Minimum number of active database connections in the deployed Connection Pool.

Default: 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

JNDI name to use by the container to query the database.

Default: 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, 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.

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
Always use the HTTPS protocol when configuring external URLs.
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

URL of the ArcGIS Enterprise portal used.

Default: //www.arcgis.com
Example: https://www.example.com/portal

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

jsregistry.browsing.enabled

Enables the HTML browsing capabilities of the JS-Registry /resources/jsregistry/root.

Allowed values: true, false
Default: true

security.ssl.trustAny

Enables support for self-signed certificates for HTTPS connections.

You should not enable this in production installations.

Allowed values: true, false
Default: false

security.login.redirect.trusted.hosts

Comma-separated list of accepted hostnames.

This list defines redirection destinations accepted if the map.apps login process is using redirects to forward the client to a specific site after successful login. This ensures that users are protected from attackers who intend to redirect them to a malicious site.

Adding hostnames to this property is only required in special situations, for example if applications are integrated with map.apps login that are deployed on a different host. This often occurs while using development projects.

Wildcards can also be used to achieve trust on a domain basis.

Default: localhost
Example: *.example.org

security.embedding.allowed.origins

Comma-separated list of origins that can embed map.apps in an iFrame.

If the embedding page is not allowed, the responses to the X-Frame-Options: DENY header request are added.

Default: <empty>
Example: https://example.com:8080,https://example.net

security.responseHeaders.common

List of HTTP headers following the Response Headers Syntax.

The headers are added to responses of the map.apps backend service. Modify this property if you have special security requirements, only.

By default, the following headers are added:

X-Content-Type-Options:nosniff

Defines that the browser should interpret responses based on the Content-Type header, only.

For more detailed information, see X-Content-Type-Options .

Strict-Transport-Security:max-age=604800

Defines that the browser should remember that the host is not allowed to be accessed via HTTP for 7 days (604800 seconds).

Applies if map.apps is accessed via HTTPS. For more detailed information, see Strict-Transport-Security .

Default: X-Content-Type-Options:nosniff,Strict-Transport-Security:max-age=604800

security.responseHeaders.manager

List of HTTP headers following the Response Headers Syntax.

The headers added to responses of map.apps manager HTML pages, like /manager or /account/login/. Modify the value of this property if you have special security requirements, only.

By default, the following headers are added:

Referrer-Policy:same-origin

Defines that the browser should send a Referrer header only to those pages visited or included that belong to the same origin as the current page.

For more detailed information, see Referrer-Policy .

Content-Security-Policy

Defines security restrictions to prevent XSS attacks.

For more detailed information, see Content-Security-Policy .

Example: Referrer-Policy:same-origin, Content-Security-Policy:default-src 'self'

Default: Referrer-Policy:same-origin, Content-Security-Policy:default-src 'self'; script-src 'self' https://demos.conterra.de https://api.github.com; connect-src 'self' https: http:; img-src 'self' data: https:; worker-src 'self' blob:; child-src 'self' blob:; style-src 'self' 'unsafe-inline'; base-uri 'self'; form-action 'self'

security.responseHeaders.apps

List of HTTP headers following the Response Headers Syntax.

The headers are added to responses of map.apps apps HTML pages, like /resources/apps/<app>/index.html. Modify this property if you have special security requirements, only.

By default, the following headers are added:

Referrer-Policy:strict-origin-when-cross-origin

Defines that the browser should send a Referrer header to pages visited or included of same origin like this page. For all other sides visited via HTTPS is a shortened Referrer header is sended.

For more detailed information, see Referrer-Policy ).

Content-Security-Policy

Defines security restrictions.

For more detailed information, see Content-Security-Policy .

Example: Referrer-Policy:strict-origin-when-cross-origin, Content-Security-Policy:default-src 'self'

Default: Referrer-Policy:strict-origin-when-cross-origin,Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-eval' https: http:; worker-src 'self' blob:; child-src 'self' blob:; connect-src 'self' https: http: wss: ws:; frame-src 'self' https: http:; img-src 'self' data: blob: https: http:; style-src 'self' 'unsafe-inline'; base-uri 'self'; form-action 'self'

Response Headers Syntax

The syntax to specify a list of response header is: <header-name>:<header-value>,<header-name>:<header-value>, where

  • <header-name> is an HTTP header name that must start with an upper case letter, and

  • <header-value> is an HTTP header value.

Proxy settings

proxy.allowedServerUrls

List of URLs to which the proxy is allowed to redirect.

map.apps provides an integrated proxy. This is needed because direct access to other resources is prohibited due to security restrictions within JavaScript.

The configuration uses the following syntax:

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

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://*.example.com/arcgis/**

Defines that access to any subdomain of example.com 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://example.com/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

  • bearer:<bearer-token> | bearer:file:<filepath-containing-bearer-token>
    A Bearer Token sent using the HTTP Authorization Header

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

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

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://www.example.com/arcgis/rest/services,token:xyz123;

  • add bearer token: http://www.example.com/arcgis/rest/services,bearer:xyz123;

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

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

Enables insecure values in the parameter proxy.allowedServerUrls.

The following configurations are considered unsafe:

  • localhost redirects. This would allow external use of localhost.

  • Configurations that only include the protocol e.g.: http://. This would allow access to all URLs through the proxy.

Default: false

proxy.use.rules

Rules for proxy access based on hostnames.

It provides more fine-grained control over which requests are routed through a proxy page.

Sample: proxy.use.rules=sample1.example.com,sample2.example.com|/proxyPage,sample3.example.com/service/
That means:
sample1.example.com is requested over default /proxy.
sample2.example.com is requested over own proxy page /proxyPage.
sample3.example.com/service/ is requested over default /proxy, but other paths from the same server are not.

CORS settings

The following settings are required for Cross Origin Request support.

map.apps assumes that requested web services support CORS. 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.

Sample:

  • http://example.net,http://example.com

  • http*://*.example.net:*
    Allows access from any subdomain of example.net via http and https from any port.

cors.request.trustedServers

List of URLs for backend services for which the transfer of security-critical information with CORS is activated.

This is the case, for example, with cookies and authorization headers.

Example: https://example.com,https://example.net

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.

Allowed values: TRACE, DEBUG, INFO, WARN, ERROR
Default: INFO

logging.file.location

Log file location.

By default, this is the folder of the tomcat log files. To create log files in the working directory of map.apps, use the value ${data.directory.location}/logs.

Default: ${catalina.base}/logs

logging.file.prefix

Name of the log files.

To prefix log files with the URL context path of the map.apps installation (for example mapapps), use the value ${webcontext.name}.

Default: ct-mapapps-webapp

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.