Configuring resources

ml-gradle deploys and configures applications via the endpoints defined by the MarkLogic Management REST API. The payloads it sends to these endpoints are defined by the files you create under src/main/ml-config (the default configuration directory).

Each of the sub-folders of src/main/ml-config maps to a configurable item in the manage API. If you need an example of what one of these files looks like, you can see the list of fields in the Management REST API docs. Simply browse to the appropriate item's properties (GET) link. For example, here is the link for databases. Simply scroll down to the Usage section at the end for a list of all the properties.

If you prefer to see a real example, you can ask MarkLogic to return the format to you by accessing the Management API directly from your browser. Simply navigate to http://localhost:8002/manage/v2 and start browsing down to the item in question. Then click on the link that says related-view : properties. Next click on the alternative formats : json link to view the json format.

Multiple configuration directories

Version 3.3.0 introduced support for multiple configuration directories via the mlConfigPaths property. A common use case for this property is for defining resources that are specific to certain environments. For example, you may have an app server that you only want deployed in your dev environment. Assuming you're using the Gradle properties plugin, you would add the following property to gradle-dev.properties:

mlConfigPaths=src/main/ml-config,src/main/dev-config

And the src/main/dev-config directory would than have a servers/my-dev-server.json file (you can pick any name you want for the config directory and the server file, these are just examples). You wouldn't need to override mlConfigPaths in gradle.properties or any other gradle-(env).properties file because it defaults to src/main/ml-config.

Generating resources

ml-gradle version 3.5.2 provides support for generating new resources from scratch - see Generating new resources for more information.

Using tokens in payload files

The contents of resource payloads often need to be altered based on the deployment environment. By default, ml-gradle registers several tokens that can be used in any payload, most of which have a default value based on the value of the "mlAppName" property:

1. %%NAME%% - typically used for a REST API server name
2. %%GROUP%% - typically used for a REST API server group
3. %%PORT%% - typically used for a REST API server port
4. %%DATABASE%% - the name of the content database
5. %%MODULES_DATABASE%% - the name of the modules database
6. %%TRIGGERS_DATABASE%% - the name of the triggers database
7. %%SCHEMAS_DATABASE%% - the name of the schemas database

You don't need to use any of the above tokens - they're primarily set to facilitate creating a new REST API application whose resources are named dynamically based on the mlAppName property - i.e. by simply setting mlAppName to "petstore", the names of common resources have an expected name:

• The REST server (if one is created) has a name of "petstore". In 3.4.0, this can be overridden via the mlRestServerName property.
• The test REST server (created if mlTestRestPort is set) has a name of "petstore-test". In 3.4.0, this can be overridden via the mlTestRestServerName property.
• The content database has a name of "petstore-content".
• The test content database (created if mlTestRestPort is set) has a name of "petstore-test-content".
• The modules database (if a REST server is created) has a name of "petstore-modules".
• The triggers database (if one is created) has a name of "petstore-triggers".
• The schemas database (if one is created) has a name of "petstore-schemas".

If you define a servers/rest-api-server.json file, it's best to keep the value of "server-name" set to "%%NAME%%" so that it can be modified either via the mlRestServerName and mlTestRestServerName properties in 3.4.0, or via the below mechanism in build.gradle in versions prior to 3.4.0:

ext {
  mlAppConfig.restServerName = "my-custom-name"
  mlAppConfig.testRestServerName = "my-custom-name-test"
}

Also, as noted above, the value of %%NAME%%, %%PORT%%, and %%DATABASE%% vary when creating a test REST API server.

NEW in version 3.2.0

Instead of having to register tokens as described below, all Gradle properties will automatically be added to the tokens map, with each property being given a default prefix and suffix of "%%". So for example, the ml-gradle property "mlHost" will be added to the token map as "%%mlHost%%". A custom Gradle property named "myProperty" will be added to the token map as "%%mlProperty%%".

This behavior is turned on by default in version 3.2.0. To turn it off, set mlPropsAsTokens to "false".

To customize the prefix and suffix, set the mlTokenPrefix and mlTokenSuffix properties.

For users familiar with Roxy token replacement, you can achieve the same behavior via these properties:

mlTokenPrefix=@ml.
mlTokenSuffix=

There's nothing special about "%%" as the default prefix and suffix; they're just the default because it's not likely to have that character string appearing in your payloads or modules.

To see all of the tokens that will be used for replacement, just run this task:

gradle mlPrintTokens

Also see How modules are loaded for more information on how token replacement works when loading modules.

Prior to version 3.2.0

You can add your own tokens via the "customTokens" Map<String, String> that's available on the mlAppConfig object. Example:

ext {
  mlAppConfig.customTokens.put("%%MY_TOKEN%%", "someValue")
  mlAppConfig.customTokens.put("ANOTHER_TOKEN", someGradleProperty)
}

Note that you don't need to use the "%%" prefix and suffix - tokens can be any string. ml-gradle just uses "%%" to make it more obvious that tokens are in fact tokens.

Also see this Wiki page in ml-app-deployer about tokens.