Deploying on offline servers

Occasionally people come across a situation where they need to deploy a slush-marklogic-node application on a server that has limited or no direct internet access for security reasons. Upon explicit request access to github.com, npm registries, and such is usually denied.

It is possible however to deploy slush-marklogic-node in such situations just as well. It will take more effort though. Then again, keep in mind you don't need to deploy the full development tooling as well. You only need what is necessary to bootstrap MarkLogic, run imports (if any), and run the middle-tier (in production mode, potentially as service).

The best approach you can take is to use two environments:

• one to build and package (connected to internet, could be your laptop, or a vm on your laptop)
• one to deploy and run (disconnected from internet)

Important note: we'll be zipping node_modules after install on the first environment. The architecture of that environment must match that of the production environment, or some of the node_modules might malfunction. If that is not an option, you might have to look into using npmbox to bring over npm packages. This does not apply to bower nor mlpm packages.

Pre-requisites

The vm or machine you use to build and package will not need the full development setup, but that is probably easiest. The least you need is:

• Node.js (which includes NPM)
• Git command-line tools
• Roxy.jar
• MLCP binary dist
• some tool to package the project (as zip, tgz, etc)

The production server should only really need:

• MarkLogic Server (potentially with Converters & Filters)
• Node.js (which includes NPM)
• Java Runtime
• and potentially the PM2 node pacakge for running the front-end as a service

Building and packaging

Prepare the environment by:

• making sure node, npm, and git are installed
• doing: npm install -g bower gulp mlpm

To simplify the steps needed on the production server, some changes are recommended to the typical slush setup:

• run: npm install --save mlpm pm2
• edit deploy/app_specific.rb to replace mlpm deploy with node node_modules/mlpm/bin/mlpm.js deploy in the deploy_packages function (only needed when using mlpm packages)
• copy local.json to prod.json, and adjust for use on the production server
• copy deploy/local.properties to deploy/prod.properties, replace local-server with prod-server, and adjust for use on the production server
• create import scripts to run on production using roxy.jar or mlcp directly (if needed)
• copy roxy.jar into the project
• unzip the MLCP binary dist into the project (could also be provided separately if preferred)

To prepare for packaging:

• npm install --only=production (skips devDependencies to save space)
• bower install
• mlpm install
• gulp build --ignoreErrors

And finish off by zipping everything (including roxy.jar and mlcp) into one big compressed file.

Deploy and run

• Unzip the package
• Cd to package home
• Verify:
  • prod.json:
    • ml-host with hostname
  • deploy/prod.properties:
    • prod-server with hostname
    • admin username and password
    • mlcp-home with full path of mlcp directory (provided in package or separately)
• Bootstrap MarkLogic with: java -jar roxy.jar prod install
• Run production import scripts (if any)
• Launch middle-tier with: node node_modules/pm2/bin/pm2 start ecosystem.json --env=prod