ryanjdew / ml-slush-discovery-app

Quick up and running app for exploring MarkLogic data, based off of the marklogic-node slush template

MarkLogic-Node Generator

This application was generated by the MarkLogic-Node Slush generator, with the following components:

• AngularJS
• Gulp
• node.js: very thin layer, hosting the Angular code and proxying MarkLogic REST API requests
• Roxy Deployer: bootstrap MarkLogic databases, application servers, etc; scaffolding for MarkLogic REST API service extensions

Install Required Dependencies

• node.js
• npm: Built-in package manager for node (comes with node, but check to be sure you have latest version: $ [sudo] npm install -g npm)
• mlpm: a MarkLogic package manager: $ [sudo] npm install -g mlpm)
• gulp: Javascript task automation ($ [sudo] npm install -g gulp)
• Bower: A package manager for front-end libraries ($ [sudo] npm install -g bower)
• Git - Roxy depends on this version control system
• Ruby - Roxy depends on Ruby in order to run server configuration scripts

Running the application

Clone this project's code into your local filesystem. Navigate to the directory where you want to install this project's code and run:

git clone https://github.com/ryanjdew/ml-slush-discovery-app.git
cd ml-slush-discovery-app

Use the included Roxy app to deploy configuration and server-side code to MarkLogic:

./ml local bootstrap
./ml local deploy modules

On Windows, that would be:

ml.bat local bootstrap
ml.bat local deploy modules

You may need to run the deploy modules command twice as there are some reports of a race condition causing it to fail. That issue will hopefully be resolved soon.

Install additional dependencies using the npm and bower package managers:

npm install
bower install

Edit ./local.json to set your ports, marklogic host, and credentials if needed. If the local.json file doesn't exist, one with default settings can be created with the command gulp init-local. The contents of local.json will appear as below.

{
  "ml-version": "8",
  "ml-host": "localhost",
  "ml-admin-user": "admin",
  "ml-admin-pass": "admin",
  "ml-app-user": "discovery-app-guest",
  "ml-app-pass": "81fdef92b84951a6",
  "ml-http-port": "8040",
  "node-port": 9070
}

Now run: gulp serve-local # this will watch the .less file for changes, compile them to .css, and run the node server

After running gulp serve-local your browser will load the application. Login with the credentials discovery-app-admin/DiscAdmin.

Follow the setup link in the user dropdown located at the top right of the page.

From there you can load data into the database from the sample-content folder.

You can then add a range index and search for the elements and properties in your database.

On the contraints tab you can select the resample button to get suggested constraints based off of the indexes that exist. Then hit save to accept the suggested constraints and you will be redirected to the Results tab to preview what the search looks like.

On the Results tab you there is a "Add Widget" link on the right. Clicking that will bring up a modal that will allow you to configure a chart. To see more details about Highcharts configurations you can go here.

Installing as service

The code includes a service script, and a service config to make installing express server service as easy as possible. The following files are involved:

• etc/init.d/node-express-service (generic express server service script)
• etc/{app}/conf.sh (application specific service configuration, any application name allowed)
• boot.js (entry point for express service, calls out to server.js)
• node-app.js (required by boot.js)

The conf.sh is 'sourced' by the service script, 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 install forever globally if it is not already installed.

• $ [sudo] npm install forever -g

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

• cd /space/projects/slush-app.live
• gulp build # this will create the ./dist/ folder with all the required assests and code
• cd /etc
• sudo ln -s /space/projects/slush-app.live/etc/{env} slush-app
• cd /etc/init.d
• sudo ln -s /space/projects/slush-app.live/etc/init.d/node-express-service slush-app
• sudo chkconfig --add slush-app
• sudo chkconfig --levels 2345 slush-app on

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

• sudo service slush-app 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.

Data

General Data Information

This application will search over XML, JSON, and text. If binary files are added through the Upload feature in the Setup section, an XML file representing the binary file will be created and searchable.

Sample Data (Optional)

The application comes with 3000 JSON documents generated by json-generator.com. You can load them with (MLCP)[https://docs.marklogic.com/guide/ingestion/content-pump] like this:

NOTE: @sample-app-role in import-sample-data.options will change base on your app's role (Alternatively, you can discover that with ./ml local info)

./ml local mlcp -options_file import-sample-data.options

Or on Windows:

ml.bat local mlcp -options_file import-sample-data.options

Troubleshooting

If you encounter any issues, please first ensure that you have the latest code from this repository with git pull. After you are updated with the latest, delete the bower_components and go through the steps in the "Running the application" section. If you still have issues, please open an issue against the project.