Below are instructions on upgrading an existing Crowd installation to the latest version of Crowd, using the automatic database upgrade.
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.
On this page:
Preparation: Read the Release Notes and Upgrade Notes
Please read:
- The Release Notes for the version you are upgrading to, and
- The Upgrade Notes for any versions you are skipping as well as the version you are upgrading to:
- Crowd 2.7 Upgrade Notes
- Crowd 2.6 Upgrade Notes
- Crowd 2.5 Upgrade Notes
- Crowd 2.4 Upgrade Notes
- Crowd 2.3 Upgrade Notes
- Crowd 2.2 Upgrade Notes
- Crowd 2.1 Upgrade Notes
- Crowd 2.0 Upgrade Notes
- Crowd 1.6 Upgrade Notes
- Crowd 1.5 Upgrade Notes
- Crowd 1.4 Upgrade Notes
- Crowd 1.3 Beta Upgrade Notes
- Crowd 1.3 Upgrade Notes
- Crowd 1.2 Upgrade Notes
- Crowd 1.1 Upgrade Notes
- Crowd 1.0 Upgrade Notes
Step 1. Shut Down Crowd and All Integrated Applications
Shut down Crowd and all Crowd-connected applications.
Step 2. Back Up your Crowd Files
- 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.
- Make backup copies of the following files:
- Back up your Crowd Home directory, in the location specified in the
crowd-init.properties
file — recommended in case something goes wrong during the upgrade process. - If your existing Crowd installation is version 1.3.x or 1.4.x: Back up the crowd.properties file for the Crowd Administration Console application, located at
{CROWD_INSTALL}\crowd-webapp\WEB-INF\classes\crowd.properties
— you will need to copy this file to your new Crowd installation.
This step is not required if your current Crowd installation is 1.5 or later. - Back up the crowd.properties file for the CrowdID application, located at
{CROWD_INSTALL}/crowd-openidserver-webapp/WEBINF/classes/crowd.properties
— you will need to copy this file to your new Crowd installation. - Back up your Crowd JDBC Driver if you have configured Crowd with a database.
- Back up your Crowd Home directory, in the location specified in the
- If you have installed Crowd on a separate application server, you need to back up your customised configuration files.
- 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 3. Re-Install Crowd
- Download Crowd.
- Unzip the download 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}.
- Point the new Crowd installation at your existing Crowd Home directory by editing the configuration file at {
CROWD_INSTALL}\crowd-webapp\WEB-INF\classes\crowd-init.properties
.
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
crowd-init.properties
file. This is found at<crowd_install_directory>/crowd-webapp/WEB-INF/classes/crowd-init.properties
- 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:
crowd.home=c:/data/crowd-home
Note: On Windows, make sure you use forward slashes as shown above, not backward slashes.
On Mac and UNIX-based systems:
crowd.home=/var/crowd-home
Important
Please, ensure that the Crowd Home directory will not match the Crowd installation directory.
- Save the
crowd-init.properties
file.
Use the same Crowd Home directory as used in your previous Crowd installation
Make sure you point the new Crowd installation at your existing Crowd Home directory so that the new Crowd can use your existing configuration.
- Open the
- Copy the following files, saved in Step 2 above, to your new Crowd installation:
- If your existing Crowd installation is version 1.3.x or 1.4.x: Copy the
crowd.properties
file for the Crowd Administration Console to the root of your Crowd Home directory.
As from Crowd 1.5, thecrowd.properties
file is located in the Home directory and not the Installation directory. This step is not required if your current Crowd installation is 1.5 or later. - Copy the
crowd.properties
file for the CrowdID application to your new {CROWD_INSTALL}/crowd-openidserver-webapp/WEBINF/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.
- If your existing Crowd installation is version 1.3.x or 1.4.x: Copy the
Step 4. Update your Integrated Applications
- If you have installed Crowd on a new server, or changed Crowd's URL or port number, you will also need to edit the
crowd.properties
file in each integrated application accordingly.
- If you are using CrowdID with an external database, you will will need to use the manual JNDI datasource configuration method to configure an external database connection.
Step 5. Start Crowd
- Run the start-up script, found in your {CROWD_INSTALL} directory:
start_crowd.bat
for Windows.start_crowd.sh
for Mac and Unix-based systems.
- Point a web browser at http://localhost:8095/crowd. You should now be able to use the Crowd Administration Console.
Troubleshooting
If you have any problems during upgrade, please raise a support request at https://support.atlassian.com/ and attach your atlassian-crowd.log
file so that we can help you find out what's gone wrong.