II.B gradle.properties reference - kghmanuel/ml-gradle GitHub Wiki
This section will focus on the values that can be supplied/controlled using the gradle.properties file
This content is based on the factory class in ml-app-deployer that reads properties from a property source object (the PropertySource interface exists to hide where the properties come from - in ml-gradle, they come from the Gradle Project class, whereas in other environments, using system properties or a java.util.Properties may be desired).
General properties
These properties are used by a variety of tasks and commands.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlAppName | Application name that is used as a prefix for creating a variety of resources, such as a REST API server and a content database. | ||
| mlCatchDeployExceptions | false | Set to true so that any command that fails when the mlDeploy task is run catches and logs an exception instead of failing the task. | 3.2.0 |
| mlCatchUndeployExceptions | false | Set to true so that any command that fails when the mlUndeploy task is run catches and logs an exception instead of failing the task. | 3.2.0 |
| mlHost | localhost | The MarkLogic host that requests should be sent to. | |
| mlPassword | admin | The password for the user defined by mlUsername. Depending on the task, can be overridden by mlRestAdminPassword, mlManagePassword, mlAppServicesPassword, or mlAdminPassword. | |
| mlPropsAsTokens | true | Set to true for all Gradle properties to be included as tokens with a default prefix and suffix of "%%". See Configuring payloads for more information. | 3.2.0 |
| mlTokenPrefix | when mlPropsAsTokens is set to true, the default prefix is "%%". Set this property to override that prefix. | 3.2.0 | |
| mlTokenSuffix | when mlPropsAsTokens is set to true, the default suffix is "%%". Set this property to override that suffix. | 3.2.0 | |
| mlUsername | admin | The default MarkLogic username for any call to MarkLogic. Depending on the task, can be overridden by mlRestAdminUsername, mlManageUsername, mlAppServicesUsername, or mlAdminUsername. |
Connection properties
In version 3.0.0, you can setup a simple SSL context while connecting to the Manage and/or Admin app servers by setting the appropriate properties below to true:
- mlManageSimpleSsl
- mlAdminSimpleSsl
Under the hood, this uses the SSLContextBuilder class in HttpClient to construct an SSLContext that trusts every request. That SSLContext is then used by the RestTemplate object that is used to connect to either the Manage or Admin app server.
If you need to setup an SSL connection in a differ manner, please see this ticket for an example of doing so within the build.gradle file. This article may help as well.
Manage server connection properties
These properties are used for connecting to the Manage app server that by default is on port 8002.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlManageCleanJsonPayloads | When set to true, ml-gradle will "clean" every JSON payload it sends to the Management API, thus removing any comments which are allowed by the underlying Jackson library, but not allowed by the Management API. Defaults to false, as there's some overhead with doing this, and many projects may not wish to allow comments in their JSON payload files. | 3.1.0 | |
| mlManageHost | mlHost | Specifies the host to connect to for Manage API operations. If not specified, mlHost is used. | |
| mlManagePassword | mlUsername | Password for the user specified by mlManageUsername. Defaults to the value of mlUsername if not specified. | |
| mlManagePort | 8002 | Specifies the port for the Manage server in MarkLogic. | |
| mlManageScheme | http | Specifies the scheme - http or https - to use when connecting to the Manage server. | 2.7.0 |
| mlManageSimpleSsl | false | Use a simple SSL context when connecting to the Manage server. | 3.0.0 |
| mlManageUsername | mlUsername | MarkLogic user for operations that require the MarkLogic "manage-admin" role. Used for all Management API operations except those that require the security role; mlAdminUsername is used for those (see that property for more information). |
Admin server connection properties
These properties are used for connecting to the Admin server that by default is on port 8001. Some Manage API endpoints are exposed on port 8001 instead of port 8002.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlAdminHost | mlHost | Specifies the host to connect to for admin-required operations. | |
| mlAdminPassword | mlPassword | Password for the user specified by mlAdminUsername. | |
| mlAdminPort | 8001 | Specifies the port for the Admin server in MarkLogic. | |
| mlAdminScheme | http | specifies the scheme - http or https - to use when connecting to the Admin server. | 2.7.0 |
| mlAdminSimpleSsl | false | Use a simple SSL context when connecting to the Admin server. | 3.0.0 |
| mlAdminUsername | mlUsername | MarkLogic user for connecting to the Admin server on port 8001. In addition, as of version 3.2.1, some commands in ml-gradle use this user - specifically, those for creating security resources. This is because those commands require that the MarkLogic user have the "security" role. If the user identified by mlManageUsername has the "security" role, then mlAdminUsername does not need to be set. |
App-Services server connection properties
These properties are used for connecting to the App-Services server that by default is on port 8000. The App-Services server is used for loading modules into an application's modules database.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlAppServicesAuthentication | DIGEST | Define which authentication strategy to use when connecting to the App-Services server. Can be BASIC, CERTIFICATE, DIGEST, KERBEROS, or NONE. | 3.0.0 |
| mlAppServicesCertFile | Defines the certificate file to use when mlAppServicesAuthentication is set to CERTIFICATE. | 3.0.0 | |
| mlAppServicesCertPassword | Defines the certificate file password to use when mlAppServicesAuthentication is set to CERTIFICATE. | 3.0.0 | |
| mlAppServicesExternalName | Defines the external name to use when mlAppServicesAuthentication is set to KERBEROS. | 3.0.0 | |
| mlAppServicesPassword | mlPassword | Password for the user specified by mlAppServicesUsername. | |
| mlAppServicesPort | 8000 | Specifies the port for the App-Services server in MarkLogic. Used for loading modules via XCC. | |
| mlAppServicesSimpleSsl | Set to "true" to use a simple SSL connection (a simple SSL context and the "ANY" hostname verifier) when connecting to the App-Services server. See Loading modules via SSL for more information on configuring an SSL connection. | 3.0.0 | |
| mlAppServicesUsername | mlUsername | MarkLogic user for connecting to the App-Services server. |
REST API server connection properties
If your application has a REST API server, these properties are used to connect to it, most often for loading REST API modules such as options, services, and transforms.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlRestAdminUsername | mlUsername | MarkLogic user for operations involving a client REST API, such as loading modules. Defaults to the value of mlUsername. | |
| mlRestAdminPassword | mlPassword | Password for the user specified by mlRestAdminUsername. Defaults to the value of mlPassword. | |
| mlRestAuthentication | DIGEST | Can be BASIC, CERTIFICATE, DIGEST, KERBEROS, or NONE. Prior to 3.0.0, this is used to choose an authentication as defined by the Java Client API's Authentication class. In version 4.x of marklogic-client-api, the Authentication class is deprecated. This property can still be used the same way it's used in 2.7.0, but it will map to the SecurityContextType enum defined in the ml-javaclient-util module. The purpose is the same - define which authentication strategy you want to use. | 2.7.0 |
| mlRestCertFile | Defines the certificate file to use when mlRestAuthentication is set to CERTIFICATE. | 3.0.0 | |
| mlRestCertPassword | Defines the certificate file password to use when mlRestAuthentication is set to CERTIFICATE. | 3.0.0 | |
| mlRestExternalName | Defines the external name to use when mlRestAuthentication is set to KERBEROS. | 3.0.0 | |
| mlSimpleSsl | When modules are loaded via the Client REST API, if the app server requires an SSL connection, then setting this property to "true" will force a simple SSL connection to be created (a simple SSL context and 'ANY' hostname verifier). |
Database and forest properties
These properties specify how databases and forests (including replicas) are created. See Creating forests for more information.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlContentDatabaseName | "mlAppName-content" | This property can be used to override that name. | |
| mlContentForestsPerHost | 3 | When a content database is created, specifies the number of forests per host for it. Only applied when the database is created via the databases/content-database.json file. | |
| mlCreateForests | true | When a database is created, this controls whether ml-gradle tries to create forests for it or not. Setting this to false is useful for when you only want to update a database's settings. | 3.1.0 |
| mlDatabaseGroups | Set the groups whose hosts forests should be created on for specific databases. This is a double-delimited string of the form "database-name1,group1 | group2,database-name2,group2 | |
| mlDatabaseHosts | Set the hosts that forests are created on for specific databases. This a double-delimited string of the form "database-name1,host1 | host2,database-name2,host2 | |
| mlDatabaseDataDirectories | Comma-delimited string of database names and forest data directories. Overrides the database-agnostic value specified by mlForestDataDirectory. | 3.2.0 | |
| mlDatabaseFastDataDirectories | Comma-delimited string of database names and forest fast data directories. Overrides the database-agnostic value specified by mlForestFastDataDirectory. | 3.2.0 | |
| mlDatabaseLargeDataDirectories | Comma-delimited string of database names and forest large data directories. Overrides the database-agnostic value specified by mlForestLargeDataDirectory. | 3.2.0 | |
| mlDatabaseNamesAndReplicaCounts | Comma-delimited string of database names and forest replica counts. Useful for when you want to configure failover for a database, and you may want to use additional properties to configure the directories for each replica forest. | ||
| mlDatabaseNamesWithForestsOnOneHost | Comma-delimited string of database names that should only have forests created on one host (and most likely, that's only one forest). Useful for databases like a modules database that have so little content that there's no point in having more than one forest. No default value. | 3.2.0 | |
| mlDatabaseReplicaDataDirectories | Comma-delimited string of database names and replica forest data directories. Overrides the database-agnostic value specified by mlReplicaForestDataDirectory. | 3.2.0 | |
| mlDatabaseReplicaFastDataDirectories | Comma-delimited string of database names and replica forest fast data directories. Overrides the database-agnostic value specified by mlReplicaForestFastDataDirectory. | 3.2.0 | |
| mlDatabaseReplicaLargeDataDirectories | Comma-delimited string of database names and replica forest large data directories. Overrides the database-agnostic value specified by mlReplicaForestLargeDataDirectory. | 3.2.0 | |
| mlDeleteForests | true | When a database is deleted via mlUndeploy, controls whether or not forests are deleted. If mlDeleteReplicas is set to true, this has no impact - currently, the forests and their replicas will be deleted together for efficiency reasons (far fewer calls to the Management API). | |
| mlDeleteReplicas | true | When a database is deleted via mlUndeploy, controls whether primary forests and their replicas are deleted first. Most of the time, you want this set to true as otherwise, the database can't be deleted. | |
| mlForestDataDirectory | Defines the default data directory for all forests created by ml-gradle. Can be overridden for a database via mlDatabaseDataDirectories. No default value. | 3.2.0 | |
| mlForestFastDataDirectory | Defines the default fast data directory for all forests created by ml-gradle. Can be overridden for a database via mlDatabaseFastDataDirectories. | 3.2.0 | |
| mlForestLargeDataDirectory | New in - defines the default large data directory for all forests created by ml-gradle. Can be overridden for a database via mlDatabaseLargeDataDirectories. | 3.2.0 | |
| mlForestsPerHost | Comma-delimited string of database-name,forest-count,database-name,forest-count,etc. Prior to 3.0.0, you can set this via mlAppConfig.forestCounts.put("database-name-", forestCount) in build.gradle. | 3.0.0 | |
| mlModulesDatabaseName | When a REST API server is created, the modules database name will default to "(mlAppName)-modules". This property can be used to override that name. No default value. | ||
| mlReplicaForestDataDirectory | Set this to define the data-directory of forests created dynamically via mlDatabaseNamesAndReplicaCounts. | 2.8.0 | |
| mlReplicaForestFastDataDirectory | Set this to define the fast-data-directory of forests created dynamically via mlDatabaseNamesAndReplicaCounts. | 2.8.0 | |
| mlReplicaForestLargeDataDirectory | Set this to define the large-data-directory of forests created dynamically via mlDatabaseNamesAndReplicaCounts. No default value. | 2.8.0 | |
| mlSchemasDatabaseName | ml-gradle defines a default token of "%%SCHEMAS_DATABASE%%" that will be replaced in payload files. This defaults to "(mlAppName)-schemas". This property can be used to override that value. | 3.0.0 |
Other resource properties
These properties specify how resources not covered above are to be deployed.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlConfigDir | Deprecated, use mlConfigPath or mlConfigPaths. | ||
| mlConfigPath | src/main/ml-config | Path to the parent directory containing all of the configuration directories. | |
| mlConfigPaths | Allows for setting multiple paths for configuration directories. Useful for when you want to have environment-specific resources. If this is set, then mlConfigDir and mlConfigPath will be ignored (there's no reason to set either if mlConfigPaths is set). If not set, then src/main/ml-config is used as the path to a single configuration directory. | 3.3.0 | |
| mlFlexrepPath | Specifies the path for Flexrep configuration files. No default value for this property, but Flexrep files by default are expected to be found at "(mlConfigPath)/flexrep". | ||
| mlGroupName | "Default" | Specifies the group that group-specific resources should be deployed to, such as scheduled tasks and app servers. | |
| mlNoRestServer | Set this to true so that mlDeploy will not create a REST API server by default. | 2.7.0 | |
| mlResourceFilenamesToExcludeRegex | Regex that defines resource filenames to exclude from processing (exclude = ignore). Useful for when you want to exclude a set of resources when deploying to a certain environment. Cannot be set when mlResourceFilenamesToIncludeRegex is also set. | 3.0.0 | |
| mlResourceFilenamesToIgnore | Comma-separated list of resource filenames that should be ignored and not deployed. Useful for when different environments require different resources to be deployed. | ||
| mlResourceFilenamesToIncludeRegex | Regex that defines resource filenames to include. If a filename doesn't match this regex, then it will be excluded (ignored). Cannot be set when mlResourceFilenamesToExcludeRegex is also set. | 3.0.0 | |
| mlRestPort | If a REST API server is created by default (will be unless mlNoRestServer is set to true), this port number is used for it. | ||
| mlSortRolesByDependencies | true | Set this to "true" or "false" for whether ml-gradle should figure out the order for deploying roles by reading each file and looking at the role dependencies. You can set this to "false" if you already are ordering your roles based on the name of each role file. | 2.9.0 |
| mlTestRestPort | If set to above zero, a test REST API server is created using this port number. |
Module and schema properties
These properties specify how modules and schemas should be loaded.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlAdditionalBinaryExtensions | Comma-delimited string of extensions for modules that should be loaded as binaries. The ml-javaclient-util library defines a number of extensions, and this can be used to add more. | ||
| mlBulkLoadAssets | true | Specifies whether or not to load asset modules in bulk - i.e. in one request, which is normally more performant than one request per module. | |
| mlDeleteTestModules | false | Specifies whether test modules should be deleted or not after modules are loaded. | 2.9.0 |
| mlDeleteTestModulesPattern | test/** | New in 2.9.0 - specifies the wildcard pattern (used with cts:uri-match) for deleting test modules. | 2.9.0 |
| mlModulePaths | src/main/ml-modules | Comma-separated list of paths for loading modules. | |
| mlModulePermissions | Comma-delimited string of role/capability/role/capability/etc that defines permissions for deployed modules. | ||
| mlModulesLoaderThreadCount | 8 | Number of threads to use when loading modules. Setting this 1 makes the modules loading process single threaded - i.e. ml-gradle won't try to load REST API services, transforms, and options in parallel. | 3.1.0 |
| mlModulesRegex | When running mlLoadModules or mlReloadModules, only load modules with a file path matching the given regex pattern. | 3.3.0 | |
| mlModuleTimestampsPath | build/ml-last-configured-timestamps.properties | Specifies the path to the timestamps file that tasks like mlLoadModules and mlWatch use for knowing whether a module file is new or modified so that modules aren't loaded over and over without any changes. | |
| mlReplaceTokensInModules | true | Enables or disables whether tokens will be replaced in module files. This is used to support Roxy-like token substitutions in modules. Also see mlUseRoxyTokenPrefix. | |
| mlSchemasPath | src/main/ml-schemas | Path to files that should be loaded into the application's schemas database. | |
| mlStaticCheckAssets | false | Specifies whether or not to statically check asset modules after they're loaded. | |
| mlStaticCheckLibraryAssets | false | Specifies whether or not to attempt to statically check asset library modules after they're loaded. If mlStaticCheckAssets is true and this is false, then no errors will be thrown for library modules. | |
| mlUseRoxyTokenPrefix | ≥3.2.0 - false<3.2.0 - true | When mlReplaceTokensInModules is set to true, then if this is true as well, tokens in modules are expected to start with "@ml.". If you do not want this behavior, set this property to false. |
Entity Services properties
These properties specify how Entity Services models should be processed.
| Property | Default value | Description | Available since |
|---|---|---|---|
| mlGenerateDatabaseProperties | true | Whether or not to generate database properties. | |
| mlGenerateExtractionTemplate | true | Whether or not to generate an extraction template. | |
| mlGenerateInstanceConverter | true | Whether or not to generate instance converters. | |
| mlGenerateSchema | true | Whether or not to generate a schema. | |
| mlGenerateSearchOptions | true | Whether or not to generate search options. | |
| mlInstanceConverterPath | ext/entity-services | Directory path for instance converters, relative to mlModulePaths. | |
| mlModelsPath | data/entity-services | Directory path for Entity Services models. |