Progress Data Cloud support

The 4.5.0 release of ml-gradle provides support for connecting to Progress Data Cloud (formerly called "MarkLogic Cloud", and also referred to as "PDC"). This guide provides details on deploying your ml-gradle-based application to PDC.

Getting started

To demonstrate this support, let's first start with the simplest set of configuration properties for connecting to PDC:

mlHost=example.beta.marklogic.cloud
mlAuthentication=cloud
mlCloudApiKey=changeme
mlCloudBasePath=/ml/ml12/default
mlForestDataDirectory=/usr/data

An explanation of each property follows:

• mlHost is always needed to tell ml-gradle which host to connect to.
• mlAuthentication tells ml-gradle to use the given authentication strategy for every connection it makes. This is useful for PDC because it's not possible to use any other strategy besides "cloud".
• mlCloudApiKey defines the PDC API key for authenticating with PDC. This API key is unique to a user and is used in place of credentials such as a username and password. See the PDC documentation on API keys for information on generating a key.
• mlCloudBasePath defines the common path for the base path that maps to each MarkLogic app server.
• mlForestDataDirectory=/usr/data is required by PDC for controlling where database forests are stored (i.e. where data is written to disk).

Configuring base paths

In PDC, all connections are made via HTTPS over port 443. Because a client cannot connect directly to a MarkLogic app server via its port, PDC defines a set of "integration endpoints" that map to each MarkLogic app server. Users will also be able to define their own integration endpoints that map to ports of app servers that they create. In ml-gradle, a base path is configured that references an integration endpoint in order to connect to an app server (the term "base path" is used because this functionality is not specific to PDC).

When a PDC instance is provisioned, a set of base paths will already be defined for the MarkLogic Manage, Admin, and App-Services app servers. These base paths will all have a common domain to them - for example:

• Manage server = /ml/ml12/default/manage
• Admin server = /ml/ml12/default/admin
• App-Services server = /ml/ml12/default/app-services

A user can then define e.g. mlCloudBasePath=/ml/ml12/default, and ml-gradle will use this to construct base paths based on the above naming convention. If a user has adjusted their base paths, they may instead define mlManageBasePath, mlAdminBasePath, and mlAppServicesBasePath so that ml-gradle knows what path to use when connecting to each of these app servers.

If you have then configured an integration endpoint in PDC for a REST API app server with a value of /ml/ml12/default/my-server, you can then set the following property:

mlRestBasePath=/my-server

Please see the PDC documentation for more information on integration endpoints.

Connecting via HTTPS

All connections to PDC require HTTPS. Depending on the Java Virtual Machine (JVM) that you are using with ml-gradle, you may need to add the certificate associated with your PDC instance to the truststore of your JVM. This will be apparent if you try to connect to PDC and receive an error like this:

Unable to call token endpoint at https://example.beta.marklogic.cloud/token; cause: PKIX path building failed

The error message of "PKIX path building failed" means that the JVM was not able to trust the certificate associated with your PDC instance, resulting in the connection failing.

Numerous articles exist on the Internet with instructions for obtaining a public certificate and adding it to your JVM's truststore; this article provides fairly clear instructions.

A tip while doing this - if your computer has multiple JVMs installed, it is easy to accidentally import the certificate into the truststore of a JVM other than the one you're using. Be sure that the "JAVA_HOME" environment variable points to the same JVM installation in the terminal window where you use keytool to import the certificate and the terminal window where you run ml-gradle.

Loading REST extensions

The mlRestPort property provides a convenience for easily creating a new REST API server in MarkLogic, which includes a content database and a modules database. ml-gradle has always used this property for two purposes - defining the port for this new app server, and also when loading REST extensions, which MarkLogic requires be loaded via the app server from which they will be used.

When deploying an application to PDC, mlRestPort can still be used for creating a new REST API server, but it cannot be used for loading REST extensions. A base path must be used instead, as the port is not directly accessible. To support this, a user defines the mlRestBasePath property based on the integration endpoint that they have configured in PDC - for example:

mlCloudBasePath=/marklogic/test
mlRestBasePath=/my-server

This will result in REST extensions being loaded via the above path - for example, a REST transform will be loaded via /marklogic/test/my-server/v1/config/transforms.

For any documents that are not REST extensions - such as data, schemas, and modules that are not REST extensions - ml-gradle will continue to default to using the App-Services app server. As noted above, the path for this is either defined via mlCloudBasePath plus "/app-services", or via mlAppServicesBasePath.

If you do not specify mlCloudBasePath, then mlRestBasePath should include the full path - e.g.

mlRestBasePath=/marklogic/test/my-server