Generator of Node.js Application Backed by MarkLogic
- 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
To run this generator, you need:
- node.js v0.10+
- npm v2+: Built-in package manager for node (comes with
node, but check to be sure you have latest version:
npm install -g npm)
npm install -g gulp)
- Slush: Application generation tool (
npm install -g slush) - only needed if you are generating the initial code
- Bower: A package manager for front-end libraries (
npm install -g bower)
- Git - Roxy depends on this version control system
- Ruby v1.9.3+ - Roxy depends on Ruby in order to run server configuration scripts
node command has been renamed to
nodejs. Some dependencies still point to
node, which is out of our control.
You may need to manually alias those commands, or install the
Microsoft Windows users should also read the Additional Microsoft Windows Requirements.
Install the Generator
The recommended way to install this generator is:
npm install -g slush-marklogic-node
To grab latest features under development you can use:
npm install -g git://github.com/marklogic/slush-marklogic-node.git
Run the Generator
Go to the directory under which your new project should be created (the parent), and run:
slush marklogic-node <app-name>
This will ask you several questions, with some intelligent defaults. The end result should be a subdirectory with a name matching the app-name, containing all the application code.
Quick Start (for the Impatient)
On Mac or Linux:
cd <app-name> npm install bower install gulp init-local ./ml local install ./ml local mlcp -options_file import-sample-data.options
cd <app-name> npm install bower install gulp init-local ml.bat local install ml.bat local mlcp -options_file import-sample-data.options
Prepare your Application
Go to the generated application directory:
npm install bower install
The generator also creates a
local.json and a
those are usually gitignored. Check if they exist. If they do, check the settings,
most importantly the port settings to make sure they list available ports. If
those files don't exist, then use the following command to create them:
Note: you can use
gulp init-dev and
gulp init-prod to setup properties for
the dev and prod environments.
Note: the deploy properties allow tweaking the MarkLogic side of the application
in great detail. Look inside
deploy/build.properties or the documentation of
the Roxy deployer to learn more about this.
Note: consider editing the
_loginMode variable in
to change the login mode of the application. The default is set to
other options are
Deploy your Application
Run the following Roxy commands to deploy the application to the chosen MarkLogic installation. It will create and configure databases, REST servers, users, and roles for you, and deploy the back-end application code.
./ml local bootstrap ./ml local deploy modules ./ml local deploy content
Or on Windows:
ml.bat local bootstrap ml.bat local deploy modules ml.bat local deploy content
Launch your Application
To launch the middle-tier, and open a browser tab automatically, you only need to run:
Note: this will also watch the
ui/ folder for changes, compile them, and reload the
browser fully automatically.
Note: to get more debug logging from Express, run with:
DEBUG=http,mail,express:* gulp serve-local
Note: it is possible to override settings on the command-line:
gulp serve-local --ml-host=<your-host> --ml-http-port=8234 --app-port=9234 --nosync
--nosync will cause no extra browsersync reload proxy to get launched at 3000,
and no browser tab will be opened automatically. In addition you have
gulp build). A few more flags are documented at the top of
Loading Sample Data (optional)
The application comes with 3000 JSON documents generated by json-generator.com. They will allow you to explore all the features you get out of the box in a better way. You can load them with (MLCP)[https://docs.marklogic.com/guide/ingestion/content-pump] using Roxy.
Before you hit off, check if Roxy can find MLCP:
./ml local mlcp
Roxy will print the following message if it cannot find MLCP:
ERROR: MLCP not found or mis-configured, please check the mlcp-home setting.
Roxy looks for
\usr\local\mlcp\) by default. It can be
convenient to just install MLCP there, or create a symlink from
to where MLCP is installed. Alternatively, edit your
mlcp-home=/path/to/your/mlcp/ to the end of it. Repeating above command
should show MLCP usage, not an ERROR.
Once MLCP works correctly, you can run:
./ml local mlcp -options_file import-sample-data.options
Or on Windows:
ml.bat local mlcp -options_file import-sample-data.options
Note: the detail controller, the part that handles showing your data, can not only handle JSON, but also XML, Binary, and Text data out of the box.
Deployment on Server
At some point you might want to deploy and run this as a service on some (demo) server. For details on that see INSTALL.mdown.
Documentation about the slush generator is provided on the Generator Wiki. It covers amongst others:
Project folder structure, which describes the project directory as produces by the generator.
Explaining the stack, which gives a brief description of the overall architecture.
Core Tools and Components, which allows you to learn more about the various tools and components used by or for the application.
Last but not least, the landing page of the out of the box application provides many more links.