Getting Started

Getting Started with MLJS Workplace couldn’t be simpler!

1. Install Node.js (Read ‘what gets installed?’ below for instructions if you don’t have Node.js installed already)
2. Install Yeoman – an application skeleton generator tool
   • Open a terminal
   • Type: sudo npm install -g yo
3. Install the MLJS Workplace Yeoman package
   • sudo npm install -g generator-mljsworkplace
4. Create a home for your new application
   • mkdir myapp
   • cd myapp
5. Generate the application with the right MarkLogic Server settings
   • yo mljsworkplace
   • Follow the prompts – particularly ensuring you don’t re-use port numbers
   • This will install dependencies using npm install. If you get an EACCESS permissions error then you need to run this command (provide password when prompted): sudo npm install
6. Install the application
   • ./mljsadmin install
   • ./mljsadmin update
   • ./mljsadmin load
7. Run the application
   • ./mljsserve
   • Point your browser at http://localhost:5001/index.html5

That’s all! You now have a working MLJS Workplace application with sample data. Feel free to re-configure the pages, or add new pages, as required

What gets installed?

mljsadmin does a lot of work. Below is a description of what happens.

MarkLogic Version 8

First off V8 isn’t supported – there are too many regression bugs in the REST API at the moment.

Installing Node.js (Manual)

For installing Node.js, you follow the Node.js install instructions. Installing node ALSO installs npm.

• Either install manually: http://nodejs.org/download/
• OR Use a package manager: https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager

When installing NPMs only install globally if you are sure you want a single version across all projects. E.g. Yeoman or the MLJS Workplace generator. Everything else is on a per project basis (this is a GoodThing[™] and considered best practice).

Whats created

MLJSAdmin will create everything for you. This includes:-

• content database called <app>-content, with 1 forest
• modules database called <app>-modules, with 1 forest
• REST API instance for content database called <app>-content-rest-<contentrestport> (Used for uploading content)
• REST API instance for modules database called <app>-modules-rest-<modulesrestport> (Used for uploading code)
• Deploy content database package (index config etc.) in to the content database
• Deploy modules database package (index config etc.) in to the modules database
• Install any triggers configured in ./data/restapi.json
• Install any rest extensions configured in ./data/restapi.json
• Deploy any initial content as described in ./data/.initial.json
• Best to choose the defaults to create an entirely new system.

HTTP Server

As for the http server port (5001) and alert port (5002), these are for the mljsserve application. I found REST API web apps are faster ran outside of MarkLogic.

Also in order to support ‘real alerting’ (as opposed to the REST API alerting support) you need a web server that uses WebSockets – which MarkLogic’s does not support (and cannot – it would need an always open connection). These two port numbers are for that Node.js webserver (mljsserve).

Customising MLJS Workplace

There are some customisations you need to do outside of MLJS Workplace currently. These are:-

• Add or modify MarkLogic REST API search options (facets etc.) – Edit the files in ./rest-api/config/options/ and deploy these using ./mljsadmin –update=searchoptions
• Alter database index settings – either via the admin console on http://localhost:8001/ or by editing the files in ./packages/databases/ and using ./mljsadmin –update=dbconfig (contentdbconfig or modulesdbconfig)

Capturing and distributing an MLJS application

I’m lazy so I created a way to do this!

• Simply run ./mljsadmin capture
• Distribute your myapp folder (except the node_modules folder) to your colleagues
• Ensure they run npm install in the folder to install dependencies (Yeoman did this for you originally, your friends will have to do this step themselves)