**Installing the Perforce Commons Web Application into a Web Server** Version 2012.

1 --------------------------------------------------------------Copyright Statement --------------------------------------------------------------Copyright 2012 Perforce Software. All rights reserved. Perforce software and documentation is available from http://www.perforce.com. You can download and use Perforce programs, but you can not sell or redistribute them. You can download, print, copy, edit, and redistribute the documentation, but you can not sell it, or sell any documentation derived from it. You can not modify or attempt to reverse engineer the programs. This product is subject to U.S. export control laws and regulations including, but not limited to, the U.S. Export Administration Regulations, the International Traffic in Arms Regulation requirements, and all applicable end-use, end-user and destination restrictions. Licensee shall not permit, directly or indirectly, use of any Perforce technology in or by any U.S. embargoed country or otherwise in violation of any U.S. export control laws and regulations. Perforce programs and documents are available from our Web site as is. No warranty or support is provided. Warranties and support, along with higher capacity servers, are sold by Perforce Software. Perforce Software assumes no responsibility or liability for any errors or inaccuracies that might appear in this book. By downloading and using our programs and documents you agree to these terms. Perforce and Inter-File Branching are trademarks of Perforce Software. Perforce software includes software developed by the University of California, Berkeley and its contributors. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). All other brands or product names are trademarks or registered trademarks of their respective companies or organizations. --------------------------------------------------------------Introduction --------------------------------------------------------------Perforce provides two ways of installing the Commons web application: 1. A virtual machine image in the Open Virtual Appliance (OVA) format. The OVA package includes the Perforce server (p4d) and the Commons web application running in a Jetty web container. It is intended for light-usage scenarios. 2. A zip file that includes the WAR file, documentation, configuration examples, and other files required to install the Commons web

application into a Jetty or Tomcat web server. This package does not include the Perforce server (p4d) or web container. This document describes how to install the Commons web application from commons.zip into a web server. For information about installing the Commons OVA package, see OVA-INSTALL.html, included with the Commons OVA download. --------------------------------------------------------------Prerequisites: --------------------------------------------------------------* Perforce server (p4d) 2010.1 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). * Jetty or Tomcat installed. See the Commons release notes for supported versions. * (Optional) P4Combine 12.1 or greater installed to enable file comparison within Commons. See the INSTALL.txt file included in the P4Combine installation zip file. --------------------------------------------------------------Installing Commons: --------------------------------------------------------------Note: The following instructions provide general installation information, with examples that are specific to the Jetty web server. See the Perforce Knowledge Base for additional Tomcat installation notes. To install the Commons web application into your web server: 1. Download the commons.zip file and extract it. 2. Copy the Commons WAR file to the webapps deployment location in the web server: $JETTY_HOME/webapps (where $JETTY_HOME is the Jetty home directory, the location of the start.jar file) 3. Configure the web server to run the WAR file by doing one of the following:

* If you are running a web server instance dedicated to Commons, copy /jetty/contexts/commons.xml from the extracted zip file to $JETTY_HOME/contexts * If you will be using /jetty/config/etc/jetty-commons.xml to launch Commons, copy /jetty/contexts/commons.xml from the zip file to $JETTY_HOME/contexts-commons Important: Jetty runs on port 8080 unless otherwise specified. jetty-commons.xml is configured to run on http port 8080 and https port 8443. When running Commons over http, passwords are sent in cleartext. For information about configuring Jetty to run using SSL (https), see http://docs.codehaus.org/display/JETTY/How+to+configure+SSL 4. Configure the runtime environment: a. Create a Commons configuration file with the following properties defined. There is a default configuration file in the WAR, (com.perforce.commons.config.properties) and two samples in the /conf folder: com.perforce.commons.config.serverProtocol=<none | ssl> (For SSL, you must have an SSL-enabled p4d server) com.perforce.commons.config.serverHost=<p4d host name> com.perforce.commons.config.serverPort=<p4d port> com.perforce.commons.config.serverPoolCapacity=<tuning variable> (Default is 200) com.perforce.commons.config.adminLogin=<p4d admin login> com.perforce.commons.config.adminPassword=<p4d admin password> com.perforce.commons.config.commonsAdminUsers=<commons administrators' user names> com.perforce.commons.config.enableUserCreation=<true | false> (True=users should be able to create accounts from the front page) com.perforce.commons.config.enableAdminCreateGroups=<true | false> (True=p4d admin account can create groups> Important: If you change any of the p4d settings referenced by the configuration file, you must update the configuration file as well. For example, if you change the admin password in p4d, you must update the adminPassword property in the Commons configuration file to prevent your Commons instance from failing. Note: If the Commons administrator cannot create groups, groups must be created in advance by a user who can, and the group owner must be set as the adminLogin account. The group name format must be "commons_group_N", where N is the internal ordinal number 0, 1, 2, etc, dictated by the p4 command, p4 counter commonsSpaceId. b. Configure the web server to refer to the Commons configuration file. Use a Java system property; for example: -D commons.configfile=file:/home/commons/commons.config.properties 5. (Optional) Configure the file compare services: a. Create the JSON configuration file to connect to a file compare service. Perforce provides P4Combine as a file compare service for use with Commons. For P4Combine installation instructions, see the

INSTALL.txt file included in the P4Combine zip file. There is a default configuration file in the WAR file (com.perforce.compare.config.json) and there are samples in the /conf folder. The defaults, which reference a default P4Combine instance, are: [ { "extension": "docx", "isExternal": true, "apiUrl" : "http://localhost:9003/compare/v1/docx", "assetBaseUrl" :"http://localhost:9003/assets", "assetPathPrefix": "/compare-docx", "compareType": DOCX }, {"extension":"png" {"extension":"jpeg" {"extension":"gif" {"extension":"jpg" {"extension":"tif" {"extension":"tiff" {"extension":"raw" {"extension":"bmp" {"extension":"pdf" {"extension":"xlsx" {"extension":"xls" {"extension":"doc" ] Note. These defaults apply only if you perform the default P4Combine installation described in the P4Combine installation instructions. b. Configure the web server to refer to the JSON configuration file. Use a Java system property; for example: -D commons.compare.jsonconfigfile=file:/home/commons/commons.compare.json 6. Start and prepare the p4d instance: * Depot: //commons * Admin user (defined as adminLogin in your Commons configuration file) 7. Start the web service by typing one of the following: $JETTY_HOME/bin/jetty.sh start (from $JETTY_HOME:) java -jar start.jar Notes: * For information about changing heap memory management settings (-Xms and -Xmx), see http://java.sun.com/docs/hotspot/ism.html ------------------------------------------------------------Running Commons and P4Combine on the same web server: ------------------------------------------------------------To run Commons and P4Combine simultaneously on the same Jetty web server: , , , , , , , , , , , , "compareType": "compareType": "compareType": "compareType": "compareType": "compareType": "compareType": "compareType": "compareType": "compareType": "compareType": "compareType": IMAGE}, IMAGE}, IMAGE}, IMAGE}, IMAGE}, IMAGE}, IMAGE}, IMAGE}, BINARY}, BINARY}, BINARY}, BINARY}

1. In $JETTY_HOME, create two context directories: contexts-commons and contexts-p4combine 2. Copy jetty/contexts/commons.xml from the Commons zip file and p4combine.xml from the P4Combine zip file into their respective directories. For P4Combine installation instructions, see the INSTALL.txt file included in the P4Combine zip file. 3. Copy /jetty/etc/jetty-commons.xml from the Commons zip file and jetty-p4combine.xml from the P4Combine zip file into $JETTY_HOME/etc 4. Start the Commons and P4Combine web services: * To run Commons: java -jar start.jar etc/jetty-commons.xml * To run P4Combine: java -jar start.jar etc/jetty-p4combine.xml * Alternately, specify both xml files to run in the same JVM