The document relates to release 2012.3 and earlier.
This document describes how to configure an existing Tomcat instance to run Commons.
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
Upgrade guidance is provided at the bottom of this article.
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 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
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
- Commons creates empty folders by creating a .commons file in the
- 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",
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
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
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:
- 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.
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:
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.
Other upgrade actions may also be required as described in the Release note.