Below is a summary of the steps required to install the Crowd WAR distribution.

The Crowd and CrowdID WAR distributions are intended for deployment onto an existing J2EE application server. This documentation assumes that you already know how to deploy a web application onto your chosen application server. If not, please contact your system administrator to assist you, or consider installing the Crowd distribution instead.

The standard Crowd installation guide tells you how to install the Crowd distribution, which includes Apache Tomcat. Instead, you may wish to deploy Crowd or CrowdID onto your own existing application server. For this purpose, we provide WAR (Webapp ARchive) distributions of the Crowd and CrowdID server applications.

Step 1. Check the System Requirements

(warning) Please check that your database and server are supported and make sure that all dependencies are installed as described below, otherwise Crowd will not run properly.

Supported Platforms

Key: (tick) = Supported. (error) = Not Supported
Java Version


Oracle JDK (1)

(tick) 1.8 (since Crowd 2.7.2).
(tick) 1.7.
(warning) 1.6 (deprecated),
(error) 1.5, 1.4

OpenJDK(tick) 1.7
Operating Systems


Microsoft Windows (2)


Linux / Solaris (2)


Apple Mac OS X (2)

(tick) 10.7 with Oracle JDK

Application Servers


Apache Tomcat (3)

(tick) 7.0.x (Crowd ships with Apache Tomcat 7.0.42)

(tick) 6.0.x



MySQL (4)

(tick) 5.0.37 and later


(tick) 11g (Tested on
(tick) 10g (Tested on


(tick) 9.2

 (tick) 8.x, 7.x

Microsoft SQL Server

(tick) 2012, 2008 R2, 2008, 2005


(tick) (For evaluation only.)

Web Browsers


Chrome(tick) Latest stable version supported

Microsoft Internet Explorer (Windows)

(tick) 8, 9, 10
(warning) 7 (deprecated)
(error) 6

Mozilla Firefox (all platforms)

(tick) Latest stable version supported
(tick) 3.x
(error) 2.x


(tick) Latest stable version supported




1. JDK:

  • It is not enough to have the JRE only. Please ensure that you have the full JDK. You can download the Java SE Development Kit (JDK) from the Oracle website.
  • Once the JDK is installed, you will need to set the JAVA_HOME environment variable, pointing to the root directory of the JDK. Some JDK installers set this automatically (check by typing 'echo %JAVA_HOME%' in a DOS prompt, or 'echo $JAVA_HOME' in a shell). If it is not set, please see Setting JAVA_HOME.

2. Operating systems: Crowd is a pure Java application and should run on any platform provided the Java runtime platform requirements are satisfied.

3. Tomcat: Deploying multiple Atlassian applications in a single Tomcat container is not supported. We do not test this configuration and upgrading any of the applications (even for point releases) is likely to break it. There are also a number of known issues with this configuration. See this FAQ for more information.

There are also a number of practical reasons why we do not support deploying multiple Atlassian applications in a single Tomcat container. Firstly, you must shut down Tomcat to upgrade any application and secondly, if one application crashes, the other applications running in that Tomcat container will be inaccessible.

Finally, we recommend not deploying any other applications to the same Tomcat container that runs Crowd, especially if these other applications have large memory requirements or require additional libraries in Tomcat's lib subdirectory.

4. MySQL: Please ensure that you set transaction isolation to 'read-committed' instead of the default 'repeatable-read', as described in the database configuration guide.

5. HSQLDB: Crowd ships with a built-in HSQL database, which is fine for evaluation purposes but is somewhat susceptible to data loss during system crashes. For production environments we recommend that you configure Crowd to use an external database.


Ensure that the following JAR files are deployed in the shared lib folder on the application server:
  • JTA (Java Transaction API)

    The JTA specifies standard Java interfaces between a transaction manager and the parties involved in a distributed transaction system: the resource manager, the application server and the transactional applications. Refer to the Sun documentation for more information.

  • JavaMail classes
  • Java Beans Activation Framework (for those using Sun JDK 1.5.x only, this is included in JDK 1.6)

    All of these JAR files are available in the Crowd Standalone Distribution zip file, available on the Crowd download centre. The files are: activation-1.1.jar, jta-1.0.1B.jar and mail-1.4.jar. You will find them in {CROWD_INSTALL}\apache-tomcat\lib (for Crowd 2.0.2 or later) or in {CROWD_INSTALL}\apache-tomcat\common\lib (for Crowd 2.0.1 or earlier).

Step 2. Install Crowd WAR

Below is a summary of the Crowd WAR installation steps:

  1. Download the Crowd WAR distribution from the Crowd download centre.
    (info) You will find the WAR archives for the Crowd and the CrowdID applications by clicking the 'Show all' link. You will need to deploy each application separately. For the rest of these instructions, we assume you are deploying Crowd WAR.

  2. Please check your unzip program before extracting the downloaded archive, as some unzip programs can cause errors — see the note on the Crowd installation front page.

  3. Unzip the download archive into a directory of your choice. We'll call it CROWD-INSTALLATION in the rest of these instructions.

  4. Specify your Crowd Home directory by editing the configuration file at CROWD-INSTALLATION/WEB-INF/classes/ The Crowd Home directory is where Crowd will store its configuration information. If you are using the embedded HSQL database, supplied for evaluation purposes, Crowd will also store its database in this directory. (Note however that the CrowdID database will be in the installation directory, not the Home directory.) To specify the Crowd Home directory:
    • Open the file. This is found at <crowd_install_directory>/crowd-webapp/WEB-INF/classes/
    • Choose the appropriate line in the file, depending upon your operating system (see below).
    • Remove the # at the beginning of the line.
    • Enter the name of the directory you want Crowd to use as its Home directory. For example,
      • On Windows:


        Note: On Windows, make sure you use forward slashes as shown above, not backward slashes.

      • On Mac and UNIX-based systems:



        Please, ensure that the Crowd Home directory will not match the Crowd installation directory.

    • Save the file.

  5. Deploy the Crowd files to your Tomcat application server. Depending upon your application server, you may need to zip up the WAR file again before deploying it. Place the CROWD-INSTALLATION directory or the WAR file into your application server's deployment directory. Please consult your application server's documentation on this point.

  6. Configure a Crowd context in your Tomcat application server:
    • Create a file called crowd.xml that contains the following context:
      <Context path="/crowd" docBase="/path/to/atlassian-crowd-war-directory" reloadable="false"/>
    • Modify the '/path/to/atlassian-crowd-war-directory' in the above element to reflect the actual path to your Crowd WAR distribution. To avoid problems with your deployment, this should NOT be Tomcat's webapps directory. If you are installing Crowd on Windows, make sure that the paths you specify for the location of the WAR file and database are full paths including drive letters.
    • Place the file in Tomcat's conf/Catalina/localhost/ directory.

  7. Create a database in your chosen database server and copy the database driver to your application server, as described in Connecting Crowd to a Database.

  8. Optional: Modify Tomcat's server.xml to allow for a Unicode character set.
    If your user directory contains usernames or group names with Unicode characters, you need to modify your Tomcat distribution's conf/server.xml file. For example, you need to do this if your user directory allows for internationalised characters in usernames.
    • In your Tomcat distribution's conf/server.xml file, find the connector definition for your HTTP protocol. The connector definition looks very much like this:
      <Connector port="8080" maxHttpHeaderSize="8192"
      maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
      enableLookups="false" redirectPort="8443" acceptCount="100"
      connectionTimeout="20000" disableUploadTimeout="true"/>
    • Add a URIEncoding="UTF-8" property to the connector:
      <Connector port="8080" maxHttpHeaderSize="8192"
      maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
      enableLookups="false" redirectPort="8443" acceptCount="100"
      connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8"/>

      This setting affects all web applications

      Because you must define this property at the connector level, this setting will affect all web applications you have deployed under the connector. This should not adversely affect the other web applications, but please be aware of this fact. Crowd and CrowdID will run fine without this property set, but you will run into issues if a username or group contains internationalised characters.

  9. Restart your application server.

  10. Point a web browser at the IP address and port that your application server is running on (typically http://localhost:8080). The Crowd Setup Wizard will start.