Roxy is a utility for configuring and deploying MarkLogic applications. Using Roxy you can define your app servers, databases, forests, groups, tasks, etc in local configuration files. Roxy can then remotely create, update, and remove those settings from the command line.
Roxy runs on any platform that runs Ruby. We currently test on Mac, Linux, and Windows.
Roxy supports multiple deployment environments. You can define your own or use the default environments: local, dev, and prod. Each environment can have different settings which are specified in properties files or xml config files.
Roxy provides scaffolding for creating REST extensions, transforms, etc. Once you have writtern your REST extension Roxy makes deploying to the server a breeze.
Whether it's a legacy application or you just prefer to configure your application using the Admin UI, Roxy can capture existing MarkLogic settings so that you can use them in your application. This feature is great for backing up Legacy Servers. Once the configurations are in Roxy you can then deploy to other servers.
Roxy works with all supported versions of MarkLogic server out of the box.
Roxy is written in Ruby. Simply by editing the app_specific.rb file you can enhance, override, or replace the default functionality.
If you work in an environment where installing Ruby is not an option you can run Roxy as a self contained jar file which embeds JRuby.
To get help with Roxy,
- Subscribe to the Roxy mailing list
- Read up on the wiki
- Check out the Tutorials page
- For Command line usage run:
$ ml -h
- A supported version of MarkLogic
- Ruby 1.9.3 or greater
- Java (jdk) Only if you wish to run the mlcp, [XQSync](http://developer.marklogic.com/code/xqsync, XQSync), or RecordLoader commands.
- Git - Required to create a new project using "ml new".
This section describes the quickest way to get started using Roxy.
- You already have one or more MarkLogic Servers running somewhere that you can access from your computer. If not, get it here.*
- You know the admin logon to your MarkLogic Server(s)
Use one of these three options to get started.
You can download Roxy using git
$ git clone git://github.com/marklogic/roxy.git
If you prefer to grab the archive simply download the latest release from our Releases Page
Roxy comes with a script that you can put in your path. This file will create new projects for you by
by issuing the $ ml new command. Grab one of these files and put it in a folder in your PATH.
Note: In order for $ ml new to work you need to have git installed.
Download the ml.bat file
Download the ml file
- Open a command prompt in the root folder of Roxy.
- Run ml init to create sample configuration files.
You must specify the --server-version option with a value of 4, 5, 6 or 7.
You must specify the --app-type with a value or rest, hybrid, or mvc.
$ ml init app-name --server-version=7 --app-type=rest
3. Modify deploy/build.properties with your application's settings.
# Username to authenticate to ML
user=your-ml-admin-username
# password for ML authentication
#
# leave this blank to be prompted for your password
#
password=
# the authentication type for the appserver (digest|basic|application-level)
authentication-method=application-level
# the default user to authenticate with. defaults to nobody
default-user=${app-name}-user
# Specify the server(s) you wish to deploy to here. This tutorial assumes you are using localhost.
local-server=localhost
#dev-server=
#prod-server=
This step is only needed when database configurations have changed or on a fresh install. In most cases you will not need to restart your server.
- Open a command prompt in the root folder of Roxy.
If your server is not configured as local-server in build.properties then substitute your environment here ( local | dev | prod ) $ ml local bootstrap- Depending on what changed you may need to restart MarkLogic in order to proceed. If you see output telling you to restart...
$ ml local restart
This step describes how to deploy your Roxy application into your MarkLogic Server modules database. If you have elected to run your code locally out of the filesystem you do not need to do this.
- Open a command prompt in the root folder of Roxy
$ ml local deploy modules
Congratulations! You have Roxy running on your server. Now you need to start customizing it.