-
Notifications
You must be signed in to change notification settings - Fork 77
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 directories in a configuration directory 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.
If you're ever unsure of what to put into a resource file, you can use a combination of the Admin UI and the aforementioned Manage API to find out what JSON or XML to add to the file:
- Configure the resource using the Admin UI - for example, add some indexes to a database
- Then go to the Manage API - e.g. host:8002/manage/v2/databases - and find the resource that you just configured, click on properties for it, and then select the JSON or XML view. This allows you to find the JSON or XML equivalent of what you just configured via the Admin UI.
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.
ml-gradle version 3.5.2 provides support for generating new resources from scratch - see Generating new resources for more information.
The contents of resource payloads often need to be altered based on the deployment environment. By default, ml-gradle registers several tokens, most of which have a default value based on the value of the "mlAppName" property.
These tokens are geared towards an application using a REST API server and optionally a separate REST API server for test purposes, along with a single triggers database and a single schemas database. They were created before the change in 3.2.0 (see below) to expose all Gradle properties as tokens. For that reason, it's best to only use these tokens in the context of creating a REST API server. Otherwise, see the section below on how all Gradle properties are exposed as tokens.
- %%NAME%% - used when deploying a REST API server
- %%GROUP%% - based off mlGroupName; defaults to "Default"
- %%PORT%% - used when deploying a REST API server; based off mlRestPort and mlTestRestPort
- %%DATABASE%% - the name of the content database or test
- %%MODULES_DATABASE%% - the name of the modules database
- %%TRIGGERS_DATABASE%% - the name of the triggers database
- %%SCHEMAS_DATABASE%% - the name of the schemas database
The above tokens are 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.
See Configuring ml-gradle for more information on configuring tokens and the mlAppConfig object.
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.
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.