Perforce Public Knowledge Base - Installing Commons in Tomcat
Reset Search
 

 

Article

Installing Commons in Tomcat

« Go Back

Information

 
Problem

Do not run on windows; this is not supported in Release 2012.x.  This applies to any web server.

The Commons application must run in your web server's root context.  This applies to any web server.

You should deploy commons.war and p4combine.war/p4review.war on separate web server instances for performance reasons.  In Release 2010.2 and later, a Tomcat instance running both commons and p4combine will not start:  you must deploy each on it's own separate instance.  Startup behavior on other unsupported web servers in unknown.

These Tomcat instructions pertain to Tomcat 7 freshly downloaded from Apache.   Alter your steps for your particular installation.

 

Solution
This information is now in the Commons Administrator's Guide.
Please consult that Document for Release 2012.4 and later.

The document relates to release 2012.3 and earlier.

This document describes how to configure an existing Tomcat instance to run Commons.

Steps:

 

  • Identify a Tomcat instance (or install a new one)
  • Identify the Perforce instance to be used with Commons
  • Download commons.zip and p4combine.zip
  • Create commons configuration files
  • Deploy Commons 

Upgrade guidance is provided at the bottom of this article.

 


Caveats

Do not run on windows; this is not supported in Release 2012.x.  This applies to any web server.

The Commons application must run in your web server's root context.  This applies to any web server.

You should deploy commons.war and p4combine.war/p4review.war on separate web server instances for performance reasons.  In Release 2010.2 and later, a Tomcat instance running both commons and p4combine will not start:  you must deploy each on it's own separate instance.  Startup behavior on other unsupported web servers in unknown.

These Tomcat instructions pertain to Tomcat 7 freshly downloaded from Apache.   Alter your steps for your particular installation.

 


Tomcat

Tomcat may be downloaded from http://tomcat.apache.org/download-70.cgi.

Tomcat install instructions are within the downloaded Tomcat distribution (zip or tar.gz); see the file RUNNING.txt.

When running Commons over HTTP, be aware that passwords are transmitted in plain text.  For Tomcat SSL configuration, see the Tomcat SSL Configuration HOW-TO.


Perforce Instance

See the Installing the Perforce Commons Web Application, Prerequisites section, for your Perforce Server (p4d) preparation.  For 2012.3:
*  Perforce server (p4d) 2012.1.473528 or higher installed.  

   Note the following p4d requirements and behaviors with Commons:

    - Spaces are implemented in part by creating groups (p4 group).
      There is an internal p4 counter (commonsSpaceId) that determines
      the next group to use. It is incremented with each attempt to
      create a space.  Space creation will fail if Commons cannot
      create or modify the next assigned group.
    - Each space requires a client (workspace) for use by the
      administrator (commons_sclient_N).  Each user has a client that
      can be used in any space (commons_uclient_<userid>).
    - The default Commons depot is //commons.
    - By default, all space files go into //commons/spaces/<space id>/
      files/... You can, however, map any depot location to an existing
      space.
    - Commons creates empty folders by creating a .commons file in the
      folder path.
    - Commons users are Perforce users (p4 user).


Download the Applications

Download the zip files containing the WAR files from http://info.perforce.com/commons-download.html.  This is the Commons application (commons.zip).  Optionally, download the Visual Diffing for Commons (p4combine.zip).  The third optional component P4Preview (p4preview.zip) may be downloaded from the ftp site at ftp://ftp.perforce.com/perforce/r12.3/bin.java/

Unzip the files and rename the war files to simply commons.war, p4combine.war, and p4preview.war.



Create the Commons Configuration Files

See the Installing the Perforce Commons Web Application, Installing Commons section, steps 4a and 5a.  You will create two files, one for configuring commons to use your p4d server and another file to describe your file compare service.

Examples of each file are in commons.zip in its conf subdirectory.

The compare service file points to the deployment of p4combine.  Change the apiUrl and assetBaseUrl to point to your tomcat's context for p4combine.war.

For example, if your p4combine web server instance is listening on the same machine but on port 9003 and you deploy p4combine.war to context /p4combine:
 "apiUrl" : "http://localhost:9003/p4combine/compare/v1/docx",
 "assetBaseUrl" :"http://localhost:9003/p4combine/assets",


Deploy Commons

Again, Commons (commons.war) must run as the root context of the web server.


Tell commons.war about your config files

Alter your web server's startup script (or equivalent) to define the java system property commons.configfile to have a value of "file:/path/to/commons.properties". Note that the value must start with string "file:".  Do the same for property commons.compare.jsonconfigfile and its file.   Setting these is only necessary for your commons.war deployment, not p4combine.war.
 
Tomcat:  for example, edit startup.sh and add commons.configfile to CATALINA_OPTS right before the "exec "$PRGDIR"":
 
export CATALINA_OPTS="-Dcommons.configfile=file:/path/to/commons.properties -Dcommons.compare.jsonconfigfile=file:/path/to/commons.compare.json $CATALINA_OPTS"

exec "$PRGDIR"/"$EXECUTABLE" start "$@"


Deploy commons.war on Tomcat

For here, we assume your Tomcat has automatic application deployment enabled (the default) and you have a "new" Tomcat installation.

Since will be deploying Commons as the ROOT context, remove all existing directories and files (especially war files) from the webapps subdirectory now.   You may move them elsewhere.

The easiest way to deploy Commons is to copy commons.war to webapps/ROOT.war:

cp commons.war $CATALINA_HOME/webapps/ROOT.war  # provide the value for CATALINA_HOME

Start Tomcat.

On startup, Tomcat will find ROOT.war and deploy them, creating the directory webapps/ROOT.

You can now access Commons with the URL to your Tomcat's host and port - http://host:port/.

Do not put commons.war into webapps with the same name of commons.war.  By default, Tomcat deploys this war with the context "commons" - http://ip:port/commons.  That URL will not work;  an enhancement request exists to allow running Commons under a non-ROOT context.

Experienced Tomcat Administrators may use alternatives, such as Tomcat's manager application, to the above methods as long as Commons runs in the root context and the java system properties are accessible to the Commons application.


Deploy optional p4combine.war

Again, this must be deployed on a separate tomcat instance.  Copy p4combine.war to tomcat's webapps directory.


Deploy commons.war and p4combine.war on other unsupported web servers

We assume you are familiar with the deployment mechanisms for your particular web server.

Again, commons.war must be deployed to the root "/" context and must be able to access the java system properties commons.configfile and commons.compare.jsonconfigfile.


Ignore commons.war INFO message for servlet-api-2.5.jar

The commons.war includes servlet-api-2.5.jar.  If you do not remove this jar then Tomcat 7 complains:

INFO: validateJarFile(/home/perforce/tomcat7/work/Catalina/localhost/_/WEB-INF/lib/servlet-api-2.5.jar)
 - jar not loaded. See Servlet Spec 2.3, section 9.7.2. 
Offending class: javax/servlet/Servlet.class
You can ignore this INFO message.  To eliminate the message, un-jar commons.war, delete WEB-INF/lib/servlet-api-2.5.jar, and re-jar.

Upgrading Commons

See the Commons Release Notes for version specific upgrade instructions.

Important:  the previous version of this technote suggested is was acceptable to deploy commons.war and p4combine.war to the same Tomcat instance.  Starting with release 2012.2 this no longer works:  you must have a separate Tomcat instance for each.

A typical upgrade requirement is to replace commons.war and/or p4combine.war.  The conservative approach to replacing the war file(s) on Tomcat is:
  • shutdown tomcat
  • in CATALINA_HOME/webapps, delete the corresponding deployment directory:
    • ROOT for ROOT.war
    • p4combine for p4combine.war
  • in CATALINA_HOME/webapps, replace ROOT.war (same as commons.war) and p4combine.war, as required.
  • restart tomcat
Other upgrade actions may also be required as described in the Release note.
Related Links

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255