Creating Environmentally Agnostic Deployments - tsgrp/HPI GitHub Wiki

Creating an environmentally agnostic Deployments

OCMS

When building OCMS as a WAR file, the war file is environmentally agnostic by default. When you are building OCMS, simply set your environment to something like below. This example is for Alfresco, but it's a similar setup for Documentum or HBase (just change your context and restServiceContext):

{
	"ocContext": "/alfresco",
	"restServiceContext": "/OpenContent"
}

Some notes:

  1. DO NOT set the host and port properties. These are only needed for development when running through grunt. If you are creating separate environments simply to update these two properties for hpi.war builds, you are wasting time. Just ignore them!
  2. If you are using OpenAnnotate, the OpenAnnotate URL must be located on the same server and port as OCMS. If this is not the case, then at the current time (Jan 2017), you must generate a new war file per environment. It is recommended to run OCMS and OA on the same server and port.
  3. If you are building against Documentum, by default OC will attempt to connect to the Data Dictionary repository. This is most likely what you want, so if that's the case, OCMS does not need to specify a repository to connect to.

An externally configurable ocms.war

The purpose of this is to configure properties (like the ones above) externally (on the tomcat) so that you can easily move the ocms.war across environments without having to modify environment specific properties on the war itself. In order to do this, you must:

  1. Create a file hpi-overrides.properties in your tomcat's shared/classes folder (from the properties setup above) and add values for each of the properties that we are injecting. * If you don't have the shared/classes folder in your tomcat, create it. Take a look at the External Properties wiki on how to set this up.

Somethings to note:

  1. All URLs in your overrides file should be relative to the base url. For example, openAnnotateURL should be openAnnotateURL=/OpenAnnotate, not openAnnotateURL=myEnv:8080/OpenAnnotate. If a fully qualified URL is needed, it will create it for you and strip out any chars that aren't digits, words or /. Therefore if you have a : it will sanitize it. Below is an example hpi-overrides.properties file.
appRoot=/ocms/

shareUrl=/share

serviceUrlRoot=/alfresco/OpenContent

openAnnotateURL=/OpenAnnotate

openAnnotateVideoURL=/OpenAnnotateVideo
  1. If you have hpi-overrides.properties in your OpenContent webapp classpath, it will take priority over the one in shared/classes directory in tomcat.

OpenContent

See: https://github.com/tsgrp/OpenContent/wiki/External-Properties

Wizard Admin

In order for the WizardAdmin.war to be agnostic, follow these steps:

  1. Do not set tomcat.home per environment. This variable is only used during build time
  2. Ensure that the webapp.home path is the same in all environments. Note - this is the path where the logs, temp and xsl folders are located. By default it's just in the webapp itself, but it doesn't have to be.
  3. Ensure that OpenContent is accessible on the same server and port as WizardAdmin
  • This is the default
  • For Alfresco, you most likely will need to set it since WizardAdmin.war is rarely deployed to the Alfresco Tomcat. Instead, do this:
    • Set the OC_REST_URL to a path starting with /. For example, set it to /alfresco/OpenContent not http://myserver:8080/alfresco/OpenContent.
    • Use Apache to proxy requests to /alfresco on port 80 to the correct port. Since HPI requires this setup due to the Same Origin Policy (See: https://github.com/tsgrp/HPI/wiki/Installation-guide#same-origin-policy), this is probably already set up.
  1. For Documentum, either:
  • Have the same docbase name in each environment (this is rare)
  • Follow the "externalizing" instructions for OpenContent and Documentum. Remove the AbtServer.properties from the WAR and place it into the shared classpath location.

OpenAnnotate

Note - as of Jan 2017, the only way to make an OA war environmentally agnostic is with the shared properties method, similar to OpenContent. Once your shared folder is set up (see the OC wiki linked to above), the following steps should be followed:

  1. Remove all environment specific properties from the war
  2. Create an openannotate-override-placeholders.properties file in the tomcat shared classpath location. Place environmentally specific properties in this file.

Note - for URL properties, we are working on something described below that will make this process easier. See below:

The only environment specific properties are typically:

ocRestEndpointAddress=
clientRequestUrl=

collaborationEndpoint=

The following best practices can ensure the war file can be ported between multiple environments:

  1. Similar to above, OA and OpenContent must be accessible from the same server and port. This can be a physical tie, or a proxy through Apache.
  2. The ocRestEndpointAddress can utilize localhost as the host name. So for example: ocRestEndpointAddress=http://localhost:8080/alfresco/OpenContent
  3. The client endpoint address can be set relatively if OpenContent and OpenAnnotate are on the same server or an Apache proxy is in place to route the request appropriately. For example: clientRequestUrl=/alfresco/OpenContent