Migrating a Roxy project to ml gradle

Version 2.9.0 of ml-gradle includes support for migrating a Roxy project into an ml-gradle project. More support will be provided in future release, but what's supported in 2.9.0 is described below.

Overview

Migrating a Roxy project into an ml-gradle project involves two high-level tasks - migrating the source files, properties, and build steps from the Roxy project files, and then exporting your Roxy project resources from MarkLogic, which requires that the Roxy project already be deployed to MarkLogic. These two tasks are described in more detail below.

Getting started

To migrate a Roxy project into an ml-gradle project, you need two things - you need Gradle installed, and you need a Gradle build file that applies the ml-gradle plugin. You can create this file in your Roxy project directory, but it's recommended to try this out first in a new directory so that you can examine the results separate from your Roxy project, as there's some overlap with the "src" directory.

So let's assume you make a new directory for your ml-gradle project - then just create a file named "build.gradle" with the following in it:

plugins { id "com.marklogic.ml-gradle" version "2.9.0" }

Running the migration tasks

Running "gradle tasks" shows the following new group of tasks in 2.9.0:

Ml-gradle Roxy tasks
--------------------
mlRoxyMigrateBuildSteps - Migrate build steps from deploy/app_specific.rb into custom Gradle tasks. Use -ProxyProjectPath to define the location of your Roxy project, and -PappSpecificPath to define a path other than deploy/app_specific.rb
mlRoxyMigrateFiles - Migrate Roxy source files into this Gradle project. Use -ProxyProjectPath to define the location of your Roxy project.
mlRoxyMigrateProject - Run all tasks for migrating a Roxy project into this Gradle project. Use -ProxyProjectPath to define the location of your Roxy project.
mlRoxyMigrateProperties - Migrate Roxy properties into the gradle.properties file in this project. Use -ProxyProjectPath to define the location of your Roxy project.

Note that the command-line property "roxyProjectPath" is required for all of the tasks.

The simplest thing to run then is "mlRoxyMigrateProject", which runs every other task:

gradle mlRoxyMigrateProject -ProxyProjectPath=/path/to/roxy/project

You can also run each task individually too, if you want to proceed more carefully and examine the output of each task before invoking another one:

gradle mlRoxyMigrateFiles -ProxyProjectPath=/path/to/roxy/project
gradle mlRoxyMigrateBuildSteps -ProxyProjectPath=/path/to/roxy/project
gradle mlRoxyMigrateProperties -ProxyProjectPath=/path/to/roxy/project

There are no dependencies between these tasks, so you can run them in any order.

The sections below have more information on each task.

Migrating source files

The "mlRoxyMigrateFiles" task copies files from the Roxy "src" and "rest-api" directories into the correct locations in the ml-gradle project. All MarkLogic modules in an ml-gradle project are under "src/main/ml-modules" - the mapping of Roxy files to directories under that directory is:

• src -> /root
• rest-api/config -> /options
• rest-api/ext -> /services
• rest-api/transforms -> transforms

Migrating properties

The "mlRoxyMigrateProperties" task copies Roxy properties from deploy/default.properties and deploy/build.properties into the standard Gradle properties file, which is gradle.properties.

This task will map known Roxy properties into their associated Gradle properties. Any Roxy property that doesn't map to a Gradle property is copied over as-is. As of version 2.9.0, the following Roxy properties are mapped:

• app-name -> mlAppName
• app-port -> mlRestPort
• user -> mlUsername
• password -> mlPassword
• group -> mlGroupName
• content-forests-per-host -> mlContentForestsPerHost

Migrating build steps

The "mlRoxyMigrateBuildSteps" task attempts to migrate custom Roxy build steps in the ./deploy/app_specific.rb file into custom Gradle tasks. This support is limited - it relies on parsing text, and it only works for build steps that executes queries. For each such build step, this task will add to the build.gradle file a new task that makes a call to /v1/eval with the same XQuery as the associated Roxy build step.

Exporting the current Roxy application

Migration plan

This information is a little out of date and is being replaced with the content above.

Here's an overview of the steps that will the tickets for Roxy migration will cover:

1. Resources (e.g. databases, app servers, users) will be migrated by exporting them via the Manage API from an already-deployed Roxy application. This avoids trying to map the Roxy config file to Manage API payloads.
2. Roxy properties will be mapped to Gradle properties and copied into gradle.properties
3. ML module files will be copied from the Roxy project into the appropriate directories in the Gradle project
4. Custom Roxy tasks in app_specific.rb will be copied into build.gradle as custom Gradle tasks
5. Any manual steps that must be performed will be documented (e.g. when a user is exported, its password is not included, so the password will need to be added manually)

In addition, support is planned for running Roxy tests from Gradle, though this is a separate effort from migrating a Roxy project and may not be supported in the same release.