David Cassel

I’ve gotten very accustomed to using the Roxy with my MarkLogic projects. However, with the new App Builder available with MarkLogic 6, some of my projects are based on JavaScript and the REST API. I still want to use the Roxy deployer, however. The simplicity of deploying configuration and code with a few simple commands isn’t something I’m willing to give up easily. Roxy doesn’t handle REST API or App Builder applications out of the box just yet (yet though I’ve filed an RFE and hope to have some time to work on it). But with a few modifications, I can still use the Roxy deployer for these projects. Here’s how.

Set the Rewriter

MarkLogic lets you specify the module that will handle URL rewriting, and Roxy provides a property to set this. In deploy/build.properties, add this line:

url-rewriter=/MarkLogic/rest-api/rewriter.xqy

The default Roxy rewriter doesn’t include REST API rewrites, and isn’t needed for an App Builder application anyway.

Set the error handler

Likewise, you can set the module that MarkLogic will call whenever there’s an uncaught exception, so that you can provide a nice error screen to your users. You can tell Roxy to use App Builder’s error page by adding this to deploy/build.properties:

error-handler=/MarkLogic/rest-api/error-handler.xqy

Global Rewrites

A new setting in MarkLogic 6 controls the scope of modules that can be used in rewriting. Global scope allows for MarkLogic-provided modules to be used for this purpose. We’ll need that, so in deploy/ml-config.xml, add this line to the http app server definition (/configuration/group:http-servers/group:http-server/group:rewrite-resolves-globally):

<rewrite-resolves-globally>true</rewrite-resolves-globally>

Add a collection

In the modules database, the files with the URI matching /marklogic.rest* need to be added to a collection. There are two steps to do this. First, find the modules database definition in deploy/ml-config.xml (look for “<database-name>@ml.modules-db</database-name>”), find the uri-lexicon setting and set it to true. (This is something I often do anyway.)

Update: I just checked in a change to the Roxy dev branch that handles this step. Add an “app-type=mvc” property to deploy/build.properties and the “ml deploy modules” command will take care of setting the collection shown below. 

Next, open deploy/app_specific.rb and add this:

def apply_modules_collections()
  r = execute_query %Q{
    xquery version "1.0-ml";

    for $uri in cts:uri-match("/marklogic.rest.*")
    return xdmp:document-set-collections($uri, "http://marklogic.com/extension/plugin")
  },
  { :db_name => @properties["ml.app-modules-db"] }
end

Get rid of the MVC code

This is an App Builder project, so you won’t be using Roxy’s default MVC code. We’ll ditch all of it and replace it with what we get from App Builder.

# from the project directory: (yes, this will delete the whole src directory.
# Make sure you're doing that on purpose.)
$ rm -rf src/*

Get the App Builder code

I’m assuming you’ve already run through the App Builder wizard and have a project. You can then use mlcp or WebDAV to get the generated source code and copy it to your src directory.

Document

In my group, we’re starting to make this common practice: replace the contents of the provided README.markdown with the set of steps needed to deploy the project. Here they are:

$ ml local bootstrap
$ ml local deploy modules
$ ml local apply_modules_collections
# and if you have some sample data:
$ ml local deploy content

Coming Soon(?)

My intention is that at some point in the future, you’ll be able to specify what kind of project you want when you create one. Right now, you make a new Roxy project like this:

$ ml new {new-app-name}

I picture something choosing between options like this:

$ ml new {new-app-name} --rest
$ ml new {new-app-name} --mvc

Most likely MVC will remain the default, but the –rest option would take care of the steps above — including applying the collection to the marklogic.rest* files so that the extra step isn’t necessary. Feel free to comment here or on the GitHub ticket to encourage us to get around to this feature.

Tags: configuration, marklogic, rest api, roxy

One Response to “Roxy and App Builder”

Leave a Reply

Name (required)

Mail (will not be published) (required)

Website