MarkLogic Cloud support

The 4.5.0 release of ml-gradle provides support for connecting to MarkLogic Cloud. This guide provides details on using that support, though as MarkLogic Cloud is evolving, this guide and ml-gradle may change based on that evolution.

Getting started

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

mlHost=example.beta.marklogic.cloud
mlAuthentication=cloud
mlCloudApiKey=changeme
mlCloudBasePath=/marklogic/test

An explanation of each property follows:

• mlHost is always needed to tell ml-gradle what host to connect to.
• mlAuthentication tells ml-gradle to use the given authentication strategy for every connection it makes. This is useful for MarkLogic Cloud because it's not possible to use any other strategy besides "cloud".
• mlCloudApiKey defines the MarkLogic Cloud API key for authenticating with MarkLogic Cloud. This API key is unique to a user and is used in place of credentials such as a username and password.
• mlCloudBasePath defines the common path for the base path that maps to each MarkLogic app server.

Configuring base paths

Regarding the concept of a "base path" - in MarkLogic Cloud, all connections are made via HTTPS over port 443. Because a client cannot connect directly to a MarkLogic app server via its port, MarkLogic Cloud defines a set of base paths that map to each MarkLogic app server. Users will also be able to define their own base paths that map to ports of app servers that they create.

When a MarkLogic Cloud 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 = /marklogic/test/manage
• Admin server = /marklogic/test/admin
• App-Services server = /marklogic/test/app-services

A user can then define e.g. mlCloudBasePath=/marklogic/test, 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.

Connecting via HTTPS

All connections to MarkLogic Cloud 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 MarkLogic Cloud instance to the truststore of your JVM. This will be apparent if you try to connect to MarkLogic Cloud 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 MarkLogic Cloud 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. We will update this page soon with a concrete example specific to MarkLogic Cloud.

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 MarkLogic Cloud, 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 mapping that they have configured in MarkLogic Cloud (note that as of February 2023, this feature is not yet publicly available) - for example:

mlRestBasePath=/marklogic/test/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.