# Upgrading Crafter CMS¶

This section details the steps required to upgrade your Crafter CMS install.

Warning

This guide assumes that you’re trying to upgrade a site from a stock 3.0.x Studio and with some slight Studio configuration changes. If your site configuration is heavily customized or your Studio is a custom overlay you might need additional work that is not specified here.

Before starting your upgrade, please review the release notes for the version you are upgrading to, which contains specific information on the changes that have been made and how it may affect you when upgrading to that specific version.

## Upgrading Crafter CMS installed using gradle¶

If you installed Crafter CMS using gradle, you can upgrade your install by following the steps below:

1. Stop your Crafter CMS
2. Perform a selfupdate to check if there has been updates to the Crafter CMS project
3. Upgrade the installed Tomcat version, Solr scripts, etc., update all the Crafter CMS components then build and deploy
4. Restart your Crafter CMS

## Upgrading Crafter CMS installed from a bundle¶

If you installed Crafter CMS from a bundle, Crafter CMS provides a couple of scripts for upgrading your installation. The upgrade script gives you an option to do a full upgrade, where your bin directory is upgraded, keeping only Tomcat’s shared folder, Tomcat’s conf folder, the Crafter Solr config, the Deployer config folder, and the crafter-setenv scripts, or, if no option is specified, the script will only upgrade the Tomcat wars and the Deployer jar.

### Running the upgrade script from a new bundle¶

Download the Crafter CMS version you’d like to upgrade to, and extract the files. To upgrade your Crafter CMS bundle, we will use the upgrade-target script. The upgrade script is located in {Crafter-CMS-install-directory}/bin/upgrade of your newly downloaded bundle. Here’s the description for the script we are going to use:

usage: upgrade-target [options] <target-installation-path>
-f,--full   Perform a full upgrade. During a non-full upgrade, only the
Tomcat wars and the Deployer jar are upgraded. During a full
upgrade, the entire bin directory is upgraded, keeping only
Tomcat's shared folder, Tomcat's conf folder, the Crafter
Solr config, the Deployer config folder, and the
crafter-setenv scripts
-h,--help   Show usage information


where:

<target-installation-path> is the path of your Crafter CMS install to be upgraded

[options] is optional. Let’s the user perform a full upgrade or to just upgrade the Tomcat wars and the Deployer jar if no option is specified

Here are the steps for upgrading your Crafter CMS install version from a new bundle:

1. Download the Crafter CMS bundle version you’d like to upgrade to
2. Extract the bundle from the previous step and go into the bin/upgrade folder
3. Run the upgrade-target script.

Here’s an example to perform a full upgrade of your current installation:

$./upgrade-target.sh -f /path/of/install/to/be/upgraded  Here’s an example to upgrade your Tomcat wars and the Deployer jar: $ ./upgrade-target.sh /path/of/install/to/be/upgraded


When performing an upgrade, the script creates a backup of your data folder then shuts down Crafter CMS. It will then backup your bin folder, then perform the upgrade (full upgrade or just upgrade the Tomcat wars and Deployer jar). Finally, it will start your Crafter CMS install again.

#### Upgrading Crafter CMS bundle versions prior to 3.0.15¶

Crafter CMS installs prior to 3.0.15 does not contain the upgrade scripts required to upgrade and will need to use the upgrade-target script to upgrade your bundle install. Please follow the steps above to upgrade your current Crafter CMS install.

### Running the upgrade script from your current install¶

Crafter CMS version 3.0.15 and up contain the upgrade scripts required to upgrade your install. Here’s the description for the script we are going to use:

usage: start-upgrade [options]
-f,--full                 Perform a full upgrade. During a non-full
upgrade, only the Tomcat wars and the Deployer
jar are upgraded. During a full upgrade, the
entire bin directory is upgraded, keeping only
Tomcat's shared folder, Tomcat's conf folder,
the Crafter Solr config, the Deployer config
folder, and the crafter-setenv scripts
-h,--help                 Show usage information
-p,--bundle-path <path>   The path of the Crafter bundle in the
filesystem. If you specify this path the URL
and version parameter will be ignored
-u,--bundle-url <url>     The URL of the Crafter bundle to download. If
you specify this URL the version parameter will
be ignored
-v,--version <version>    The community version of the Crafter bundle to


where:
[options] is optional. Let’s the user perform a full upgrade when -f is used or to just upgrade the Tomcat wars and the Deployer jar otherwise. If no other option is specified (aside from -f), it will upgrade your install to the latest available Crafter CMS bundle version.

The start-upgrade script downloads the Crafter CMS version that you specify that you would like to upgrade to, then creates a script upgrade script in {Crafter-CMS-install-directory}/temp/upgrade that performs the specified upgrade you would like performed (full upgrade or just upgrade the Tomcat wars and Deployer jar).

To upgrade your current Crafter CMS install:

1. Go to your bin/upgrade folder
2. Run the start-upgrade script. The start-upgrade script downloads the Crafter CMS bundle version you would like to upgrade to. This will create a script upgrade.sh|bat in {Crafter-CMS-install-directory}/temp/upgrade.
3. Go to {Crafter-CMS-install-directory}/temp/upgrade and run the upgrade.sh|bat script

Here’s an example to perform a full upgrade of your current install to a certain version

$./start-upgrade.sh -f -v 3.0.16$ cd ../../temp/upgrade
$./upgrade.sh  Here’s an example to perform a full upgrade of your current install using a bundle url $ ./start-upgrade.sh -f -u https://download/url/to/bundle
$cd ../../temp/upgrade$ ./upgrade.sh


Here’s an example to perform a full upgrade of your current install using the path where your bundle was downloaded

$./start-upgrade.sh -f -p /path/to/bundle$ cd ../../temp/upgrade