Page tree
Skip to end of metadata
Go to start of metadata

Below are instructions on upgrading an existing Crowd installation to the latest version of Crowd, using the procedure that transfers your Crowd data via XML backup.

Check that this is the right upgrade procedure for you

Please check that you have chosen the recommended upgrade procedure for your database server and Crowd version before you start.

In summary, you will need to:

  • Back up your Crowd database to XML before starting the upgrade.
  • Do a clean installation of Crowd, pointing to a new Crowd Home directory.
  • Restore your database from the XML backup as part of the setup process.

On this page:

Preparation: Read the Release Notes and Upgrade Notes

Please read:

Step 1. Export your Crowd Database to XML

In the Crowd Administration Console, click the 'Administration' tab and then click 'Backup'. Follow the screen prompts to back up your Crowd database to an XML file. For full instructions, see our guide on backing up data.

Step 2. Shut down Crowd and All Integrated Applications

Shut down Crowd and all Crowd-connected applications.

Step 3. Back Up your Crowd Files

  1. Use your database backup tools to back up your Crowd database and your CrowdID database. We highly recommend this step, in case something goes wrong during the upgrade process and you need to restore your data from backup.

  2. Make backup copies of the following files:
    • The file for the CrowdID application, located at
      {CROWD_INSTALL}/crowd-openidserver-webapp/WEB-INF/classes/ — You will need to copy this file to your new Crowd installation.
    • Your Crowd JDBC Driver if you have configured Crowd with a database — You will need to copy this file to your new Crowd installation.
    • Your customised configuration files, if you have installed Crowd as a WAR distribution — You will need to copy these files to your new Crowd installation.
    • Your Crowd Home directory, in the location specified in the file — Recommended in case something goes wrong during the upgrade process.

  3. We recommend that you rename your existing {CROWD_INSTALL} directory, because legacy files may cause problems if you unzip the new Crowd installation into an existing directory.

Step 4. Download and Re-Install Crowd

  1. Download Crowd.

  2. Unzip the downloaded archive into a directory of your choice, taking note of the following:
    • Please make sure that your new {CROWD_INSTALL} directory has a different name from your old {CROWD_INSTALL} directory.
    • Please check your unzip program before extracting the downloaded archive – see the note on the Crowd installation front page.
    • Do not specify directory names that contain spaces.
    • We will refer to this installation directory, where you unzipped the archive, as {CROWD_INSTALL}.

  3. Specify a new Crowd Home directory for your new Crowd installation, by editing the configuration file at {CROWD_INSTALL}\crowd-webapp\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.

    Make sure you point the new Crowd installation to a new Crowd Home directory, so that Crowd will do a clean installation. Do not point it at your existing Crowd Home directory.

  4. Copy the following files, saved in Step 3 above, to your new Crowd installation folder:
    • Copy the file for the CrowdID application to your new {CROWD_INSTALL}/crowd-openidserver-webapp/WEB-INF/classes directory.
    • Copy your Crowd JDBC Driver if you have configured Crowd with a database.
    • If you have installed Crowd as a WAR distribution, copy your customised configuration files.

Step 5. Start Crowd and Run the Setup Wizard

  1. Run the start-up script, found in your {CROWD_INSTALL} directory:
    • start_crowd.bat for Windows.
    • for Mac and Unix-based systems.

  2. Point a web browser at http://localhost:8095/crowd where you will see the Crowd Setup Wizard.

  3. Enter your license key on the 'License' screen, as described in the instructions on the Setup Wizard.

  4. When asked for your Installation Type, choose 'Import data from an XML Backup'. This step is required, to import your Crowd data from the XML file which you created in Step 1 above.

  5. The Setup Wizard will now ask you to configure your database. Supply the JNDI datasource or JDBC connection details of a new database.

  6. The Import Existing Crowd Data screen will appear. Enter the location of your XML backup file and click 'Continue'.

  7. The Setup Wizard is now complete. You are now ready to log in to the Crowd Administration Console, using your administrator account from your earlier Crowd installation.

Step 6. Update your Integrated Applications

  1. If you have installed Crowd on a new server, or changed Crowd's URL or port number, you will also need to edit the file in each integrated application accordingly.

  2. If you are using CrowdID with an external database, you will need to use the manual JNDI datasource configuration method to configure an external database connection.


If you have any problems during upgrade, please raise a support request at and attach your atlassian-crowd.log file so that we can help you find out what's gone wrong.

  • No labels