You can use custom server settings to configure Mendix Runtime beyond the standard possibilities offered by Studio Pro.
Only use this functionality if you know exactly what you are doing. Incorrect values can prevent Mendix Runtime from starting.
Each custom setting consists of a name and a value. For example, to enable persistent sessions you add a custom setting with name
PersistentSessions and value
true. For a more detailed list of settings and example values, consult full-documented-m2ee.yaml.
If you are running your app on the Mendix Cloud, you can access these settings in the Developer Portal via Environments > Environment Details > Runtime > Custom Runtime Settings. For more information see the Runtime Tab section of Environment Details.
If you are running on SAP Cloud, you can add custom settings as User-Provided Variables prefixed with
MXRUNTIME_. If the setting contains a dot
. you can use an underscore
_ in the variable.
When you are running your app locally, you can set these values in a Configuration.
There is more information on how this is done in the Cloud Foundry buildpack in Configuring Custom Runtime Settings in the GitHub repo.
2 General Settings
The following custom settings can be configured:
|ApplicationRootUrl||Can be used within Java actions to get the public location of the application. Useful when the HOST header is not available, for example when including a URL to the application when sending e-mails from a scheduled event.||In Mendix Cloud, https://[domain].mendixcloud.com|
|CACertificates||A comma-separated list of paths to CA certificates.|
|ClientCertificatePasswords|| Comma-separated list of passwords for Client Certificates (should match the ClientCertificates order). Example:
|ClientCertificates|| Comma-separated list of paths to Client Certificates. Example:
|ClientCertificateUsages|| Only use this when you have multiple client certificates and you want to configure specific certificates for specific servers.
This setting defines which service must use which client certificate. The value of this setting must be a comma-separated list of key/value items. A key/value item must be specified as
For web services, use the imported web service name as the identifier.
For REST services, use the host name of the remote server as the identifier.
Please note that any backslash in the path must be doubled. The whole value must be enclosed by braces (
|ClusterManagerActionInterval|| The interval (in milliseconds) used for performing all cluster manager actions. These actions include, unblocking users, and removing invalid sessions. If nothing is specified the interval is half the
||300000 (5 minutes)|
|com.mendix.core.SameSiteCookies|| The SameSite property can be included in all cookies that are returned by the embedded HTTP server. The possible values are
|com.mendix.core.SessionIdCookieName||Defines the name of the cookie value which represents the session id. Can be useful to change when running in a container which assumes a certain name for the session cookie.||XASSESSIONID|
|com.mendix.core.StorageService|| Defines which storage service module will be used. The storage service module takes care of storing the actual files associated with
|com.mendix.storage.PerformDeleteFromStorage||Defines whether a delete of a Mendix file document should result in an actual delete in the storage service. A reason to not perform an actual delete in the storage service can be when it is also used as a backup service.||true|
|EnableApacheCommonsLogging||Some libraries used by the Mendix runtime use Apache Commons for logging. By default these log messages are suppressed. Set this value to
|http.client.CleanupAfterSeconds||For the call REST service and call web service activities, the first request to a new host will create an HTTP client that will handle subsequent requests. When there are no new requests to the host for the specified time, the HTTP client will be cleaned up. A value of
If the infrastructure provider closes this connection before this cleanup time, you can receive a
|http.client.MaxConnectionsPerRoute||The maximum number of connections for a route for call REST service and call web service activities.||2|
|http.client.MaxConnectionsTotal||The maximum number of connections allowed across all routes for the call REST service and call web service activities.||20|
|JavaKeyStorePassword||Password for the default Java keystore.||changeit|
|LongLivedSessionTimeout|| This setting is the same as
||604800000 (7 days)|
|MyScheduledEvents|| A comma-separated string with the names of the events. Please don’t forget the name of the module (a name can be, for example,
|NoClientCertificateUsages||Comma-separated list of host names or imported web service names that should never be contacted using a client certificate.|
|PersistentSessions||Defines whether sessions will be persisted in the database or not. When sessions are persisted, statistics will be made about logged-in users. When the Runtime server restarts, sessions still exist and users don’t have to sign in again. In a clustered environment you must have persistent sessions. The only exception is for on-premises installations which have implemented sticky sessions. The value can be true or false.||true|
|ScheduledEventExecution|| Specify which scheduled events should be executed. Choices are
|SessionTimeout||Defines after how much time session becomes invalid (in milliseconds). After that timeout a session becomes applicable for removal. The session will not be destroyed until the next time the cluster manager evaluates the active sessions.||600000 (10 minutes)|
|TaskQueue.ShutdownGracePeriod||Time in ms to wait for task in a task queue to finish when shutting down.||10000|
|TempPath||The location of the temporary files.||[deployment folder]\data\tmp|
|TrackWebServiceUserLastLogin|| Defines whether to update the web service user’s
|UploadedFilesPath|| The location of the uploaded files. A valid path can be:
3 Log File Settings
The settings below influence the behavior of the log files. These settings can only be used on premises. In the cloud, these settings do not change any behavior.
|LogFileName||The name of the log file. The log files (actual log file plus back-up files) will be placed in the folder specified by the setting log path.||Application.log|
|MaxLogFileSize||The maximum size per log file. When the log file reaches this maximum size, the log file will be backed up and a new empty log file will be used.||2097152 (2 MB)|
|MaxLogFileCount||The maximum count of log files preserved (actual file plus back-up files). When the maximum count is reached, the oldest backup file will be removed.||10|
4 Database Settings
4.1 Common Settings
|ClientQueryTimeout||Defines the timeout in seconds for most of the database queries which are executed to load data into client widgets, like data grids. After the duration as specified here, a query will be canceled and an exception will be thrown.|
|DatabaseType||Defines the database engine which is used as the Mendix database. Valid values are
|DatabaseUserName||Name required for authentication to the database.|
|DatabasePassword||Password for the
|DatabaseHost||The host name and optionally the TCP port number of the database. Use a colon (
This will be overridden if you supply
|DatabaseName||The name of the database or schema used by the Mendix app
This will be overridden if you supply DatabaseJdbcUrl.
|DatabaseJdbcUrl||Defines the JDBC URL to use for the database connection (which overrides the other database connection settings).|
|DatabaseUseSsl||For PostgreSQL databases, defines whether the connection will be made using SSL without certificate validation. If you need certificate validation, use DatabaseJdbcUrl instead.||false|
|LogMinDurationQuery||Defines whether database queries are logged via the
|DataStorage.EnableDiagnostics||This setting can be used to generate a uniqueness constraint violation report.||false|
|UseNetworkTimeout||This setting is applied to PostgreSQL and DB2. It affects the timeout mechanism used when reserving new ids for Mendix objects. If set to true, the socket level request timeout is used. In that case, the request timeout is handled within the operating system. If set to false, the timeout is handled by Mendix runtime. For other databases, timeouts are always handled by Mendix runtime.||true|
|JdbcLoginTimeout||This setting defines the database connection establishment time in milliseconds.||5000|
4.2 Connection Pooling
The settings below are used to define the database connection pooling behavior. Mendix Runtime uses a pool of reusable database connections. You can, for example, define how many connections can be used. Connection pooling is implemented using the Apache Commons Object-pooling API .
These settings are configured per runtime instance. If you have scaled your application, the number of connections on the database side will be multiplied by the number of runtime instances. For example, if you set
50 and scale your app to 2 runtime instances, each runtime instance will create at most 50 connections, but on the database side this will lead to a maximum of 100 connections.
|ConnectionPoolingMaxWait||When the maximum number of “active” objects has been reached, the pool is said to be “exhausted.” The “when exhausted” action used by the connection bus is
|ConnectionPoolingMaxActive||Sets the cap on the total number of active instances from the pool.||50|
|ConnectionPoolingMaxIdle||Sets the cap on the number of “idle” instances in the pool.||50|
|ConnectionPoolingMinIdle||Sets the minimum number of objects allowed in the pool before the evictor thread (if active) spawns new objects. Note that no objects are created when
|ConnectionPoolingTimeBetweenEvictionRunsMillis||Sets the number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run.||300 000 (5 minutes)|
|ConnectionPoolingSoftMinEvictableIdleTimeMillis||Sets the minimum amount of time an object may sit idle in the pool before it is eligible for eviction by the idle object evictor (if any), with the extra condition that at least
||300 000 (5 minutes)|
|ConnectionPoolingNumTestsPerEvictionRun||Sets the maximum number of objects to examine during each run of the idle object evictor thread (if any). When a negative value is supplied,
4.3 Migration Settings
The settings below are used to define the source database from which all data should be copied to the main database. You have to specify the settings below only once. The main database should exist and should be empty. During the app start-up, the data will be copied if the settings below are specified. Remove the settings afterwards, because they are not needed anymore.
Before the data copy process starts, the source database will also be brought in line with the model, like the main database. This is necessary to make it possible to copy all the data without problems.
|SourceBuiltInDatabasePath||Defines the file location of the built-in source database. This setting is only necessary if a non-default location of the built-in database has to be used to copy the data from.||[deployment folder]/data/database|
|SourceDatabaseHost||The host name and optionally the TCP port number of the source database. Use a colon as separator between host name and port number. Possible values are:
|SourceDatabaseJdbcUrl||Defines the JDBC URL to use for the source database connection (which overrides the other source database connection settings). This feature is not supported for PostgreSQL databases.|
|SourceDatabaseName||The name of the source database.|
|SourceDatabasePassword||The password for the connection to the source database.|
|SourceDatabaseType||The type of the source database. Possible values:
|SourceDatabaseUseIntegratedSecurity||This setting defines whether integrated security should be used for SQL Server. If true, user name and password will not be used.||false|
|SourceDatabaseUseSsl||For PostgreSQL databases, defines whether the connection to the source database will be made using SSL.||false|
|SourceDatabaseUserName||The user name for the connection to the source database.|
5 S3 Storage Service Settings
The settings described below influence the behavior of the Amazon S3 Storage Service module. This module can be used for both Amazon S3 Storage and IBM Cloud Object Storage.
For deployments to the Mendix Cloud, SAP BTP, and Mendix for Private Cloud these settings are managed for you and cannot be overwritten.
|com.mendix.storage.s3.AccessKeyId||Acts as the username to authenticate with the S3 service.|
|com.mendix.storage.s3.SecretAccessKey||Acts as the password to authenticate with the S3 service.|
|com.mendix.storage.s3.BucketName||Name of the bucket where the files are stored on S3.|
|com.mendix.storage.s3.ResourceNameSuffix||Suffix for the keys under which objects are stored. This can be used when S3 buckets are divided into different segments for different users with different credentials (for example, store objects as
|com.mendix.storage.s3.PerformDeleteFromStorage||Deprecated. Use com.mendix.storage.PerformDeleteFromStorage.
Defines whether a delete of a Mendix File Document should result in an actual delete in the storage service. A reason to not perform an actual delete in the storage service can be when it is also used as a backup service.
|com.mendix.storage.s3.Region||Sets the region in which the S3 bucket is located. This will be used to determine the service endpoint, unless overridden in com.mendix.storage.s3.EndPoint. This setting will also be used as the signing region for requests.|
|com.mendix.storage.s3.EndPoint||Overrides the default endpoint. This setting is required when the storage is on a non-AWS location (for example, IBM Cloud Object Storage). Both the endpoint (for example,
|com.mendix.storage.s3.UseV2Auth||Lets the authentication policy use
|com.mendix.storage.s3.EncryptionKeys||List of keys which can be used to encrypt and decrypt data at rest in S3. The right key to decrypt the data with is automatically selected depending on with which key it was encrypted. Each encryption key consists of a key id, the encryption algorithm and the actual key (Base64 encoded). Example:|
|com.mendix.storage.s3.MaxConnections||Overrides the default maximum connections limit in the S3 service. The default value is enough for most applications, so we do not recommend explicitly setting this to a custom value unless a larger maximum connections limit is absolutely necessary.||DEFAULT_MAX_CONNECTIONS field of the ClientConfiguration interface in the AWS SDK for Java.|
|com.mendix.storage.s3.ClientExecutionTimeout||Sets the amount of time (in milliseconds) to allow a call to the storage service to complete. A value of
||0 (no timeout)|
|com.mendix.storage.s3.ConnectionTimeout||Sets the amount of time to wait (in milliseconds) when initially establishing a connection before giving up and timing out. A value of
||10.000 (10 seconds)|
|com.mendix.storage.s3.SocketTimeout||Sets the amount of time to wait (in milliseconds) for data to be transferred over an established, open connection before the connection times out and is closed. A value of
||50.000 (50 seconds)|
|com.mendix.storage.s3.RequestTimeout||Sets the amount of time to wait (in milliseconds) for the request to complete before giving up and timing out. A value of
||0 (no timeout)|
|com.mendix.storage.s3.UseCACertificates||Set this value to
6 Microsoft Azure SQL
These settings can be changed to use a Microsoft Azure SQL database for your Mendix application. For deployments to the Mendix Cloud, SAP BTP, and Mendix for Private Cloud these settings are managed for you.
First, you need to create an Azure SQL database (for information on how to do this, see this SQL Database Tutorial). Make sure your Azure firewall settings allow your Mendix application to reach the Azure SQL database (by default, the Azure firewall does not allow external connections).
7 Microsoft Azure Blob Storage Settings
These settings can be used to store files using the Microsoft Azure blob storage service. Server-side encryption can be configured through the Azure Portal (for more information, see Azure Storage encryption for data at rest). For deployments to the Mendix Cloud, SAP BTP, and Mendix for Private Cloud these settings are managed for you.
|com.mendix.core.StorageService||Has to be set to
|com.mendix.storage.azure.AccountName||Account name to authenticate with the Azure blob storage service.|
|com.mendix.storage.azure.AccountKey||Account key to authenticate with the Azure blob storage service.|
|com.mendix.storage.azure.SharedAccessSignature||Provides delegated access to resources in your storage account. For more information, see Shared Access Signature on docs.microsoft.com.|
|com.mendix.storage.azure.BlobEndpoint||Set the blob endpoint. This setting is required when authentication by
|com.mendix.storage.azure.Container||Name of the container containing the blob.|
|com.mendix.storage.azure.CreateContainerIfNotExists||Indicates whether to check if the container exists, and creates it if it does not exist.||
|com.mendix.storage.azure.ParallelismFactor||Maximum number of parallel multi-part file uploads/downloads. We advise not changing this setting unless you experience slow file transfers for large files. Choosing larger values will lead to higher memory usage.||5|
|com.mendix.storage.azure.UseHttps||For enabling or disabling secure connections using HTTPS. Can be
|com.mendix.storage.azure.TimeoutIntervalInMs||Sets the amount of time (in milliseconds) to allow a call to the storage service to complete. For more information, see the Azure libraries.||No timeout|
|com.mendix.storage.azure.MaximumExecutionTimeInMs||Sets the maximum execution time (in milliseconds) to use when making this request. For more information, see the Azure libraries.||No maximum time|
Azure blob storage’s default connection protocol is HTTPS in order to encourage secure connections by default. This is a highly recommended best practice (for more information, see Configure Azure Storage Connection Strings). This should now be transparent, unless you use custom domain names (for details, see Require Secure Transfer). In that case, you should use the
UseHttps setting above to revert to the previous default behavior and disable HTTPS.
8 IBM Cloud (Bluemix) Object Storage Settings
These settings can be used to store files using the IBM Cloud object storage service. For deployments to the Mendix Cloud, SAP BTP, and Mendix for Private Cloud these settings are managed for you.
Mendix supports unscoped authentication of OpenStack Identity (Keystone) v3. The credentials related settings must be filled with the corresponding values which can be found in the Service Credentials section of your object storage service.
Unlike other storage services, IBM Cloud does not provide server-side encryption.
|com.mendix.core.StorageService||Has to be set to
|com.mendix.storage.swift.Container||Container name of the object storage service|
|com.mendix.storage.swift.Container.AutoCreate||If enabled (value
|com.mendix.storage.swift.credentials.DomainId||Unique identifier of the domain|
9 Web Client Settings
The settings below influence the behavior of the Mendix web client.
|EnableKeepAlive||Defines whether the web client sends a keep alive request every SessionTimeout/2 milliseconds, to prevent a session timeout. Each click in the browser also acts as KeepAlive. Disabling this property will result in a user being logged out automatically after 10 minutes of inactivity, even if the browser remains open.||true|
|PhoneUserAgentRegEx||Defines the regular expression that is used to determine whether a user is visiting a Mendix application from a phone. The regular expression is matched against the user-agent header sent by the client’s web browser.||Android, Mobile (iPhone, iPod, BlackBerry)|
|TabletUserAgentRegEx||Defines the regular expression that is used to determine whether a user is visiting a Mendix application from a tablet. The regular expression is matched against the User-Agent header sent by the client’s web browser.||Android, iPad|
|com.mendix.webui.HybridAppLoginTimeOut||Determines how many minutes your token will remain valid before re-authenticating using your full credentials. This setting defaults to
|com.mendix.webui.FeedbackSizeWarningThreshold||A warning is logged when the feedback size exceeds the threshold. Feedback is sent from server to client to instruct (for example, to refresh objects or to open a page). They are serialized as “instructions” in the server response. If there are too many instructions, this can have performance implications, as they all have to be serialized to the client. For this reason, a warning is logged when the threshold is exceeded.||5000|
|com.mendix.webui.StateSizeWarningThreshold||A warning is logged when the state size exceeds the threshold. The state consists of changes in objects and of objects not committed to the database (yet). If there is too much state, this will have performance implications, as the whole state has to be serialized to the client. For this reason, a warning is logged when the threshold is exceeded.||100|
|com.mendix.webui.CommittedObjectsThreshold||The threshold controls how much data is sent back to the client after executing a microflow. By default, we send back full objects when they are changed or committed. When this threshold is reached, only object GUIDs are sent back instead so that the client knows about the changes while the amount of data sent over the network is reduced. The client will then retrieve the objects later on, if needed.||100|
10 Metrics Settings
|Metrics.Registries||Registries to send metrics to|
|Metrics.ApplicationTags||Common tags used for every meter|
11 Proxy Settings
The settings below allow you to use a proxy.
These settings have to be set as JVM properties, not as custom Runtime settings.
|http.proxyHost||Defines the hostname of the HTTP proxy server.|
|http.proxyPort||Defines the port number of the HTTP proxy server.|
|https.proxyHost||Defines the hostname of the HTTPS proxy server.|
|https.proxyPort||Defines the port number of the HTTPS proxy server.|