Demo Catalog

npm install
bower install
./ml local bootstrap
./ml local deploy modules
./ml local deploy content
gulp

If the app-port specified in build.properties is already occupied and you want to change it for your local environment, do the follow:

• create and edit deploy/local.properties and set app-port to the port where you want it (you may need to change xcc-port as well)
• pass --ml-port=???? to the gulp server command. So if you set the port to 8123, run "gulp --ml-port=8123"

Likewise, if you are running MarkLogic on a different host than where you are running the user interface, pass --ml-host to the gulp server command.

Data

You can find the sample data set at ssh.marklogic.com:/home/dcassel/projects/demo-cat/demo-cat.zip. Load it with:

$ ./ml local mlcp import -input_file_path <path to dir with zips or zip itself> -input_compressed –document_type xml

You will need to set the mlcp-home property in your local.properties file for this to work. For instance:

mlcp-home=/Users/dcassel/software/mlcp-Hadoop2-1.2-1

Deployment on server

A local git repo has been setup on the server, add it as a remote to your local git:

• git remote add prod [email protected]:/space/projects/demo-cat.git

Then run the following each time you want to update code on the demo server:

• git push prod

Ask IT for sudo rights, you might need to chown files to a shared group to have write access.

Once done that, you can run all above deployment steps on the server, just go to /space/projects/demo-cat.live/. A few ml commands might return an error, but only after having done what needed to be done.

Installing as service

The code includes service scripts, and service configs to make installing express server service and gulp watch service as easy as possible. The following files are involved:

• etc/init.d/node-express-service (generic express server service script)
• etc/init.d/node-gulp-service (generic gulp watch service script)
• etc/{env}/conf.sh (env specific service configuration, any env name allowed)
• startup.js (entry point for express service, calls out to server.js)
• server.js (called by both gulp server and startup.js)
• gulpfile.js (entry point for gulp service, which executes default task)

The conf.sh is 'sourced' by the service scripts, and allows overriding the built-in defaults. Usually you only need to override SOURCE_DIR, APP_PORT, and ML_PORT. Make sure they match the appropriate environment.

Next step is to push all source files to the appropriate server. The following assumes it was dropped under /space/projects/ in a folder called demo-cat.live. Take these steps to install the services:

• cd /etc
• sudo ln -s /space/projects/demo-cat.live/etc/{env} demo-cat
• sudo ln -s demo-cat demo-cat-watch
• cd /etc/init.d
• sudo ln -s /space/projects/demo-cat.live/etc/init.d/node-express-service demo-cat
• sudo ln -s /space/projects/demo-cat.live/etc/init.d/node-gulp-service demo-cat-watch
• sudo chkconfig --add demo-cat
• sudo chkconfig --add demo-cat-watch
• sudo chkconfig --levels 2345 demo-cat on
• sudo chkconfig --levels 2345 demo-cat-watch on

Next to start them, use the following commands (from any directory):

• sudo service demo-cat start
• sudo service demo-cat-watch start

These services will also print usage without param, but they support info, restart, start, status, and stop. The info param is very useful to check the settings.

Configuring HTTPS

Easiest way to do this is to configure SSL in httpd. Make sure mod_ssl and openssl are installed:

• sudo yum install mod_ssl openssl

Then use openssl to generate a key, a CSR (Cert Sign Request), and self-cert the CSR:

• sudo openssl genrsa -out catalog.key 2048
• sudo openssl req -new -key catalog.key -out catalog.csr
• sudo openssl x509 -req -days 365 -in catalog.csr -signkey catalog.key -out catalog.crt

You will need to enter Country, Company, and server name for the CSR. You can also use the CSR to get a Certificate signed by a third party (IT will likely be able to help with that).

Copy the output files in the right location:

• sudo cp catalog.crt /etc/pki/tls/certs/
• sudo cp catalog.key /etc/pki/tls/private/
• sudo cp catalog.csr /etc/pki/tls/private/

Next is configuring httpd. Make sure the ssl.conf points to the correct catalog.key (SSLCertificateKeyFile) and catalog.crt (SSLCertificateFile)

• sudo vi +/SSLCertificateFile /etc/httpd/conf.d/ssl.conf

You probably also want to unwrap ssl.conf from the

• sudo vi +/VirtualHost /etc/httpd/conf/httpd.conf

Make sure you have both of these enabled:

NameVirtualHost *:80
NameVirtualHost *:443

And then insert the following at the end:

<VirtualHost *:80>
  ServerName catalog-new.demo.marklogic.com
  Redirect permanent / https://catalog-new.demo.marklogic.com/
</VirtualHost>
<VirtualHost *:443>
  SSLEngine on
  ServerName catalog-new.demo.marklogic.com
  RewriteEngine On
  RewriteCond %{HTTPS} on
  RewriteRule ^(.*)$ http://localhost:4000$1 [P]
</VirtualHost>

You can verify httpd config with:

• sudo /usr/sbin/httpd -S

For official signing, you need to forward the catalog.csr to IT. They will send two pem files in return: one for the Cert Authority (ca.cert.pem), and a replacement for the catalog.crt file (catalog.demo.cert.pem). Put both in the certs folder, and make sure SSLCertificateFile points to catalog.demo.cert.pem, and SSLCACertificateFile to ca.cert.pem.

Roxy

Roxy (RObust XQuerY Framework) is a lightweight framework for quickly developing well-structured, easily maintained XQuery applications. Roxy was heavily inspired by Ruby On Rails and CakePHP.

Getting Help

To get help with Roxy,

• Subscribe to the Roxy mailing list
• Read up on the wiki
• Check out the Tutorials page

Components

Roxy Deployer

Roxy Deployer makes managing MarkLogic application easy. Simply edit a few configuration files and you have full access to create and deploy applications to MarkLogic servers, local or remote. Roxy Deployer is written in Ruby and is easily extended to add additional functionality.

Roxy mVC

The meat and potatoes of Roxy, the mVC (with a de-emphasis on m) is a light-weight MVC framework fashioned after Ruby on Rails and CakePHP. It relies heavily on Convention over Configuration.

Roxy Unit Tester

What good is your code if it doesn't work? Testing is paramount to the development process. The Roxy Unit Tester tests XQuery with XQuery. Write your tests in XQuery and run them from the UI or from the command line. Roxy Unit Tester produces JUnit XML output so you can use it with your favorite continuous testing tool.

Requirements

• MarkLogic (notes on supported versions):
  • MarkLogic 4.x - You need the Docs appserver running on port 8000 - this port can be overridden in build.properties
  • MarkLogic 5.x - You need the Manage appserver running on port 8002 - this port can be overridden in build.properties
  • MarkLogic 6.x - You need the Manage appserver running on port 8002 - this port can be overridden in build.properties
• Ruby 1.9.3+ - Required for Roxy Deployer only.
• Java (jdk) - Only if you wish to run the Roxy Deployer [XQSync](http://developer.marklogic.com/code/xqsync, XQSync) or RecordLoader commands.
• Git - Required to create a new project using "ml new".

Getting Started (Quick Version)

This section describes the quickest way to get started using Roxy.

Assumptions

• 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)

Download Roxy

$ git clone git://github.com/marklogic/roxy.git

Configure your application

1. Open a command prompt in the root folder of Roxy
2. Run ml init to create sample configuration files (must specify --server-version option with a value of 4, 5, 6 or 7)

$ ml init app-name --server-version=[version-number]

3. Modify deploy/build.properties with your application's settings.

# Username to authenticate to ML
user=your-ml-admin-username
# password for ML authentication
password=your-ml-admin-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=nobody
# Specify the server(s) you wish to deploy to here. This tutorial assumes you are using localhost.
local-server=localhost
#dev-server=
#cert-server=
#prod-server=

Configure MarkLogic 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.

1. 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 )
2. $ ./ml local bootstrap
3. Depending on what, if anything, you changed you may need to restart MarkLogic in order to proceed. If you see output telling you to restart...

$ ml local restart

Deploying Code

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.

1. Open a command prompt in the root folder of Roxy
2. $ ml local deploy modules
3. Open your favorite web browser to http://localhost:port

Sub in your hostname and port from build.properties

Congratulations

Congratulations! You have Roxy running on your server. Now you need to start customizing it.

Getting Help

For more information run: $ ./ml -h