Building and Deploying HPI 2.x From Source (deprecated as of Jan 2018) - tsgrp/HPI GitHub Wiki

In order to run HPI 2.1+, the following need to be installed on your system:

Environment Setup - Windows and Linux

Node.js

Various releases of Node, as well as upgrading to the latest version, is made easy with nodist. Grab it from https://github.com/marcelklehr/nodist and follow the DIY installation instructions. (NOTE: the git command will install it to the directory the command is run from). Note - be sure to install node version 4.x and make it your "global" node version.

  • Run the installer
  • Test that you can run NPM by opening a command window, running the command npm -v and verifying that it outputs an installed version

Grunt

Run the following commands:

  • npm install -g grunt-cli
  • NOTE: if you have multiple versions of HPI on your machine, you may want to run npm install grunt-cli to avoid anything clashing with your global npm loaded libraries.
  • Verify that you can run the commmand: grunt -version (it should just spit out the version number)

Project Builds

Navigate to your HPI project (dir with Gruntfile.js) and run the following command:

  • npm install
  • NOTE: if you are having problems downloading some packages due to SSL errors, run the following command: npm config set strict-ssl false - or better yet, update the npm version you are using

This will install the required node-modules for HPI.

Development and Deployment

Common Development Build Projects

For internal TSG development, the following projects are typically used:

Scenario HPI Project OC Project
HPI against Documentum. (Default repository is hpi_dev_71 dctm or wizard-dctm hpiDctm or wizardDctm
HPI against local Alfresco alfresco or wizard-alfresco hpiAlfresco or wizardAlfresco
HPI against HBase hpi-demo-hbase wizardHbase

Organizing a New HPI Project

Project Folder

Creating a project folder is simple:

  • In $HPI_HOME$/project/ create a folder with whatever you want to call your project
  • Create a project/PROJECTNAME/app/configs/config-project.js file. This file is used for specifying custom configuration options, such as URL paths and custom actions for clients.
  • To use/set an ApplicationID that is different than default you simply add the appId property to the app/modules/hpiadmin config for your project. It should just be the desired ApplicationID without any leading or trailing slashes.

The config-project.js file is useful for action customizations for clients. Please see the article on Overriding an action for more information on customizing actions for a client.

Now you can use your project with the command line arg --project=PROJECTNAME, detailed in the "Building and Running HPI" section below.

Within your project folder you may override existing core HPI files or create project specific files (such as actions and unit tests).

Overriding an existing core HPI file

Please use EXTREME CAUTION when overriding files. Pay careful attention to your extension strategy and consider if there is an opportunity to extend the core file rather than completely override it.

To override an existing core HPI file, add a file with the same name as the file you wish to override in a similar folder structure.

For example, if I wanted to override the file:

$HPI_HOME$/app/modules/actions/checkin.js

I would add the following file to my project folder:

$HPI_HOME$/project/PROJECTNAME/app/modules/actions/checkin.js

Adding a project specific file

Any additional files you include in PROJECTNAME/app or PROJECTNAME/assets will be copied on top of the default application files.

So if I have a new action for my project I need to add, I can add the file to the following location:

$HPI_HOME$/project/PROJECTNAME/app/modules/actions/myNewAction.js

Environment Files

Where projects should contain configurations and customization common to a specific project, environment files contain configurations specific to the environment the application will run in. Things like URLs, ports and paths the application will need to run. These settings will be different for each environment a project is built for (Dev/QA/Prod/etc.).

HPI handles environment settings through the use of env.json files. The file should be named with the convention COMPUTERNAME.json and be placed in:

$HPI_HOME/project/PROJECTNAME/env/COMPUTERNAME

You can also provide app, asset, and hpi-wrapper overrides at this level if you have to change a file by environment.

You specify the env you want to use with the --env option. If a project was provided the build script will look in the project directory first before falling back to the main env folder.

\\This command will look for HPI_HOME/project/abbvie/env/kedzie.json, throwing a warning if neither is found.
--project=abbvie --env=kedzie

You can look at another env for formatting examples, but it should be JSON with the following keys:

  • context: The location you want your proxy (node.js) or serviceURLRoot (apache/tomcat) to make calls to. Defaults to /OpenContent. Alfresco builds need to set to /alfresco.
  • restServiceContext: The REST endpoint to use in constructing the serviceUrlRoot. Defaults to /rest.
  • port: [node.js only:] port your node.js service proxy (OpenContent) should point to. Defaults to 8080.
  • host: [node.js only] hostname your node.js service proxy sends OC calls to
  • tomcatHome: [Tomcat only] The Tomcat home location to deploy the built hpi.war file to during the build.
  • configOverrides : This object will be overlayed on top of the requirejs config last.

Here's an example of an env file for a Documentum project (works for both node.js and tomcat builds):

{
	"context" : "/OpenContent", //not necessary unless you are on alfresco, but showing for illustrative purposes
	"restServiceContext": "/rest", //not necessary unless you are on alfresco, but showing for illustrative purposes
	"host" : "localhost", //only necessary for projects being run on node.js
	"port": 8080, //only necessary for projects being run on node.js
	"tomcatHome" : "C:/apache/apache-tomcat-6.0.37", //only necessary if running tomcat build
	"configOverride" : {
		"config" : {
			"app" : {
				"root" : "/hpi/" //only necessary if you are calling the war something different than hpi.war. Typically this will also be set to "/" for a node.js build which will run hpi at the root of localhost:9000
			}
		}
	}
}

Additionally you can also provide ocContext, ocServer, and ocPort options on the command line for on the fly env swaps:

--ocContext=/oc-wizardDctm --ocPort=9080 --ocServer=10.1.1.140

Using Project folders for Client Styles

Project folders are an effective way to create a customized look and feel for a client:

  • In your project folder, create an assets folder if there is not one already
  • Create a css folder inside assets
  • Create a client.css file inside the css folder that contains imports to your various stylesheeets you would like to customize. For example: @import "styles/cmhr.styl"; You can optionally put the markup right into client.css but this is not best practice and you won't be able to leverage Stylus
  • Add a styles folder inside css and add your .styl files and any markup necessary. Be sure that you are being HIGHLY SELECTIVE with your CSS Selectors, as to not cause issues with other styles outside of your customization!
  • Images can be added inside the styles directory, to a folder called img - they will be copied into the build img folder.

Building and Running HPI

Here is the basic build process:

  • Copy all of assets/ and app/ to BUILD directory
  • If an project is applied copy the project/assets and project/app/ into the BUILD directory
  • If an env is supplied copy the project/env/{ENVNAME}/assets and project/env/{ENVNAME}/app/ into the BUILD directory on top of the core folders (overriding)
  • Combine the Core, Action and Project configs into a single config file.
  • Compile all the styles to a single file
  • Create an index.html file in the BUILD directory (different files depending on build level)

And if this is debug/release does the above plus:

  • optimize all js files into a single file
  • minify the combined require.js and index.css
  • compress the minified require.js and index.css
  • Copy all the necessary files from the BUILD directory to the dist directory

There are a few deployment levels as follows:

  1. dev - Use for development
  2. debug - Optimized - Use for debugging a release build
  3. release - Optimized, minified, compressed - Use for production

The first deployment level is useful for development and runs on a node server. Use the server target to start a server and 'watch' the application files. When you change a file in your application it is automatically deployed to the server (this can take a few seconds). So all you have to do is refresh the page.

grunt clean server --project=myproject --env=computername

The clean command is important, because if you deleted files, they will remain in the BUILD folder the next time you build, which will cause a false sense of security since these files are really gone.

The next two levels are debug and release. They are almost the same, except in release, all js and css files are minified and compressed. With these levels you have two target options:

  • distDebug/distRelease - These targets place the ready to go application in the DIST directory. From there you can copy the files onto a server for deployment.
  • serverDebug/serverRelease - If you want to try out the debug/release code on the node server. NOTE: There is no watch setup, so if you make changes you'll have to re-run the build.

Note: You can use the --verbose flag with any of the build commands to see more log info if you are experiencing issues.

Deploying HPI

Tomcat

Add the desired Tomcat root path to your computername.json env file (see cambridge.json for an example):

"tomcatHome" : "C:/apache/apache-tomcat-6.0.37"

and run the command:

grunt tomcatDebug --project=myproject --env=computername

This command will create a war file called hpi.war in the DIST directory. If you have a tomcat root path specified it will also copy the built war file to tomcatRoot + /webapps/.

Apache HTTP Server

To create a static directory for use with an Apache HTTP Server, run the following command:

grunt distDebug --project=myproject --env=computername

This command will create a static web directory in the DIST folder. This can be placed in a directory specified in your Apache httpd.conf file. Note that your configuration will have to rewrite all incoming requests to /index.html.

Backend Setup (OC)

HPI's main connection to a repository is through OpenContent. We use its RESTful API to interact with the content server.

Installing OC in Alfresco

See this page in the OpenContent wiki for information on how to build OC as an Alfresco Subsystem.

Installing OC for any other repository (ex: Documentum, Solr)

See this page in the OpenContent wiki for information on how to build an OpenContent.war file.