# Stash Latest (2.12) : Stash upgrade guide

Created and last modified by pwatson on Apr 02, 2014

This page describes how to upgrade Stash from a previous version.

- For the latest and greatest Stash release, see Releases.

For production environments we recommend that you test the Stash upgrade on a QA server before deploying to production.

Please also read:

- the Supported platforms page for the full list of supported platforms for Stash.
- the End of support announcements for Stash.
- the Integrating Stash with Atlassian applications page for version compatibility information.

On this page:

## Upgrade steps

This section provides general instructions for upgrading Stash. See also the specific notes on this page for the version of Stash you are upgrading to. We strongly recommend that you upgrade Stash by following these steps:

#### 1. Stop Stash!

To stop Stash, change directory in a terminal or command prompt to the `<Stash installation directory>` and run:

- Windows:

      bin\stop-stash.bat

- Linux and Mac:

      bin/stop-stash.sh

#### 2. Back up your Stash data!

Back up the Stash home directory. This is where your Stash data is stored. The home directory location is defined:

- On Windows: by the `STASH_HOME` environment variable, or by the `STASH_HOME` line of `<Stash installation directory`>`/bin/setenv.bat`.
- On Linux and Mac: by the `STASH_HOME` line of `<Stash installation directory`>`/bin/setenv.sh`.

If you are using an external database, back up this database. Follow the directions provided by the database vendor to do this.

See Data recovery and backups for more information.

#### 3. Download and install Stash as usual

Download Stash from the Atlassian download site and unpack the archive file to a suitable location.

- Note that you should not simply copy the unpacked Stash directory over an existing Stash directory. Copying a new Stash directory over the existing one is not supported – that will always corrupt the system. This is because each version of Stash includes versioned jar files, such as `stash-model-2.4.1.jar`. If you copy these, you end up with multiple versions of Stash's jar files in the classpath, which leads to runtime corruption.

Update the value of `STASH_HOME` in the new Stash installation directory to point to your existing Stash home directory (but note that if you use a `STASH_HOME` environment variable to specify the home directory location then no change is required):

- On Windows, update the home directory location as defined by the `STASH_HOME` line of the new `<Stash installation directory`>`/bin/setenv.bat`.
- On Linux and Mac, update the home directory location as defined by the `STASH_HOME` line of the new `<Stash installation directory`>`/bin/setenv.sh`.

If you made custom changes to the configuration of your existing Stash installation

Icon

If you made custom changes to the configuration of your existing Stash installation you will have to make these changes for the new installation as well. For example:

- Changes to port, context path, and/or access protocol (`conf/server.xml)`
- Use of 64-bit libraries on Windows instead of the out-of-the-box 32-bit libraries (`bin/tomcat7.exe, bin/tcnative-1.dll`)

Do not simply copy the configuration files from your existing Stash installation to your new installation. Carefully review the differences between your customized version and the default version and re-apply your custom changes to the new configuration files to prevent overwriting configuration changes between different versions of Stash.

If you are using MySQL

Icon

Stash does not ship with the MySQL database driver.

You need to reinstall the driver in the new installation, or copy the previous driver from the old `<Stash installation directory>/lib` to the new `<Stash home directory>/lib.`

#### 4. Start Stash

To start Stash, change directory in a terminal or command prompt to the `<Stash installation directory>` and run:

- Windows:

      bin\start-stash.bat

- Linux and Mac:

      bin/start-stash.sh

Note that the database schema migration task that runs when Stash is started after an upgrade can take a while, especially if the upgrade has skipped a few releases (for example, upgrading from Stash 2.2 to 2.7). Stash should never be interrupted while this is happening, even if Stash appears to have hung – allow the server to either come up, or fail to come up (when it will provide an explanation of what went wrong).

#### 5. Rollback

If necessary, rolling back an upgrade should only be performed by restoring a backup of both the Stash home directory and the Stash database – rolling back requires a consistent home directory and database. You can then reinstall the previous version of Stash to the `<Stash installation directory`>.

## Upgrading to Stash 2.12

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash. In particular, note that support for Java 6 is deprecated. Stash 3.0+ will require Java 7.
- the Stash 2.12 release notes.

Note that:

- Stash does not yet support Java 8.
- Stash 2.12 does not support Git 1.8.4.3
- Stash does not support the Apache HTTP Server `mod_auth_basic` module.

See Supported platforms.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-4533 | Comment on repository settings entry for "Default branch" are confusing | Open
Authenticate to retrieve your issues

1 issue

## Upgrading to Stash 2.11

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash.
- the Stash 2.11 release notes.

Note that Stash does not support Git 1.8.4.3, nor does Stash support Java 8 yet. See Supported platforms.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
Authenticate to retrieve your issues

No issues found

## Upgrading to Stash 2.10

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash.
- the Stash 2.10 release notes.

Note that Stash does not support Git 1.8.4.3. See Supported platforms.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-4254 | Unknown error when clicking on JIRA link in a pull request | Open
Authenticate to retrieve your issues

1 issue

## Upgrading to Stash 2.9

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash.
- the Stash 2.9 release notes.

Note that Stash does not support Git 1.8.4.3. See Supported platforms.

#### Pull Request Ref Optimization

When you first start Stash after upgrading to Stash 2.9 a repository upgrade task runs that optimizes the pull request refs for all repositories managed by Stash. It's important that you do not interrupt this upgrade process. You can track the progress of this in the Stash logs. See STASH-3469 - Pull request references in the Git repository are never removed after merge or decline Closed .

#### Backup Client Upgrade Required

Version 1.0.3 of the Stash Backup Client is required to back up Stash 2.9.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
Authenticate to retrieve your issues

No issues found

## Upgrading to Stash 2.8

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash.
- the Stash 2.8 release notes.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-3884 | Non-ASCII values used as branch model prefixes/branch names don't work in MSSQL | Open
| STASH-3909 | Creating a branch containing double quotes in the name will fail on Windows | Open
| STASH-3908 | Creating a branch in Stash with a prefix that matches an existing branch will fail | Open
Authenticate to retrieve your issues

3 issues

## Upgrading to Stash 2.7

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash.

#### Repository System Information Plugin is now deprecated

The functionality of the repository system information plugin has now been moved into core Stash. The plugin will still work for Stash 2.x versions but is redundant as of Stash 2.7.

#### MySQL default isolation level

Stash 2.7.x uses READ_COMMITTED instead of the MySQL default isolation level (REPEATABLE_READ). This can result in exceptions when installing or upgrading to 2.7.x, if binary logging is enabled in your MySQL server. More details and a fix can be found in this KB article.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-3990 | Mismatches in SQL Server database names cause inscrutable migration errors | Open
| STASH-3891 | Git's native .mailmap handling generates 500 errors in Stash for Git 1.8.2 to 1.8.4 | Open
| STASH-3803 | Specifying 'since' and 'until' parameters on commits list only works if there aren't enough commits to trigger infinite scroll | Open
| STASH-3773 | Number of required approvals doesn't get updated when approving | Open
Authenticate to retrieve your issues

4 issues

## Upgrading to Stash 2.6

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-3687 | Application navigator use wrong URL | Open
Authenticate to retrieve your issues

1 issue

## Upgrading to Stash 2.5

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-4417 | RepositoryService#countByProject does not take into account repositories that are publicly accesible | Open
| STASH-3702 | Invalid markdown list rendering | Open
| STASH-3635 | Html in PR comments not encoded | Open
| STASH-3624 | SocketException on Solaris 10 | Open
| STASH-3589 | Vertical alignment of back link on user profile screen is off | Open
| STASH-3251 | NPE in SshScmRequestCommandAdapter.java:238 | Open
Authenticate to retrieve your issues

6 issues

#### Limited support for JIRA 4.4.x and earlier

JIRA 4.3+ allows for showing commits associated with issues in JIRA. However, viewing issues within Stash is not supported for JIRA 4.4.x and earlier. See JIRA compatibility for details.

## Upgrading to Stash 2.4

Please also see:

- the Upgrade steps section above.
- the End of support announcements for Stash.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-3419 | In full source display mode, longest line is cut off if horizontal scroll bar | Open
| STASH-3163 | Driver not available when running Stash as Windows service using $STASH_HOME/lib | Open
Authenticate to retrieve your issues

2 issues

## Upgrading to Stash 2.3

Please also see the Upgrade steps section above.

When upgrading to Stash 2.3 you also need to upgrade the SCM Cache plugin, due to recent Stash API changes.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-3461 | Stash upgrade task does not check for database schema validity | Open
| STASH-3308 | Git command authentication failure causing the user to enter captcha before maxmimum attempts are met. | Open
| STASH-3296 | Using "Load newer activities" on pull requests drops some activities | Open
| STASH-3279 | URL not linked correctly when surrounding by parenthesis | Open
Authenticate to retrieve your issues

4 issues

## Upgrading to Stash 2.2

Please see the Upgrade steps section above.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-3295 | Comment Date format changes from relative to absolute dates unexpectedly | Open
| STASH-3251 | NPE in SshScmRequestCommandAdapter.java:238 | Open
Authenticate to retrieve your issues

2 issues

## Upgrading to Stash 2.1

Please also see the Upgrade steps section above.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-3163 | Driver not available when running Stash as Windows service using $STASH_HOME/lib | Open
Authenticate to retrieve your issues

1 issue

#### Install location for third-party libraries

As of Stash 2.1 you can install third-party libraries and jar files, such as the MySQL JDBC driver, into `<Stash home directory>/lib`. This has the advantage that files in this location are not overwritten, and lost, when you upgrade Stash.

#### Microsoft SQL Server JDBC driver

Stash 2.1 now uses the Microsoft SQL Server JDBC driver to access Microsoft SQL Server, instead of using the jTDS driver. In most cases, Stash will automatically swap to using the Microsoft driver on upgrade and no configuration is required.

If Stash was configured to use Microsoft SQL Server by manually entering a JDBC URL, please refer to this guide.

## Upgrading to Stash 2.0

This section provides specific notes for upgrading to Stash 2.0. See also the Upgrade steps section above.

#### Tomcat

For Stash 2.0, Tomcat has been upgraded from version 6 to 7. As part of that upgrade, the `server.xml` file has changed. If you have customised `server.xml` (for example, for `port`, `path` or `hostname`), you can not simply copy your own version across to the upgraded Stash; you must reapply your customisations to the `server.xml` file for the new version of Stash.

If you were running Stash as a Windows service and are upgrading from 1.x to 2.x you will need to reinstall the Stash service to make it use Tomcat 7.

To uninstall the Stash service you need to execute following commands from <STASH DISTRIBUTION DIR>\bin:

    > net stop <service name>
    > service.bat uninstall <service name>

You can call this command without the service name if you installed the Stash service with a default name.

After the service is uninstalled you can proceed with the Upgrade steps and Running Stash as a Windows service instructions to configure Stash 2.x running as a service.

#### Perl

Stash 2.0 requires Perl for its branch permission functionality. If Perl is unavailable, Stash 2.0 will not start.

On Windows machines, Perl will only have been installed by the Git installer if the correct install option was chosen at Step 4 of Installing Stash on Windows.

#### Existing Git hooks

In order to support Branch Permissions, Stash 2.0 moves existing hooks in the `pre-receive` and `post-receive` folders under `<STASH_HOME>/data/repositories/NNNN/hooks` (where NNN is the internal repository id) to `.../hooks/pre-receive.d/10_custom` or `.../hooks/post-receive.d/10_custom`. Consequently, custom hooks that use relative path names (e.g. "./foo.sh" or "../dir/foo.sh") will be broken by the upgrade to Stash 2.0.

#### Deprecation of Internet Explorer 8

Support for Internet Explorer 8 is deprecated from the release of Stash 2.0. The official end-of-support date is yet to be determined. See Supported platforms for details.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-2862 | Non-ASCII values used in branch permissions don't work in MSSQL | Open
| STASH-2898 | Tomcat fails to start up on 64-bit Windows with error tc-native-1.dll: Can't load IA 32-bit .dll | Open
| STASH-2889 | Markdown: colon ':' in image urls is not accepted by current implementation of markdown | Open
Authenticate to retrieve your issues

3 issues

## Upgrading to Stash 1.3

This section provides specific notes for upgrading to Stash 1.3. See also the Upgrade steps section above.

#### Email server

An email server must be configured in Stash so that email notifications for pull request events can be sent. Please see Setting up your mail server for details.

#### Upgrading from Stash 1.3 beta

Click to see information about upgrading from the beta...

Stash 1.3 uses improved commenting compared to the 1.3 beta. This means that when you upgrade from the beta to Stash 1.3:

- Pull request comments made in the beta against the diff will only appear in the activity, and not in the diff, in Stash 1.3. Future comments made on the same pull request in Stash 1.3 will behave as expected.
- Reviewers, participants and watchers were added after the beta was released. After you upgrade, existing pull requests will not have participants or watchers. You can add reviewers by editing the pull requests and any future commenters will be added as a participant and watcher to the pull request as you would expect.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-2818 | The latest custom JIRA issue key regex is not used to reindex the old commits | Open
| STASH-2744 | Pull Request race condition between push and attributed activity author | Open
Authenticate to retrieve your issues

2 issues

## Upgrading to Stash 1.2

Please see the Upgrade steps section above.

#### Known issues

T | Key | Summary | Status
--- | --- | --- | ---
| STASH-2746 | Windows service behaves poorly (doesn't shut down, reports successful startup too early) | Open
Authenticate to retrieve your issues

1 issue

## Upgrading to Stash 1.1

Please see the Upgrade steps section above.

## Upgrading from Stash 1.0.x to 1.1 or higher

Please also see the Upgrade steps section above.

#### SSH

When you restart Stash after upgrading to 1.1, Stash will automatically enable SSH access to your repositories, on the default port of 7999.

If you want to change the port, or are hosted behind a proxy or firewall, you may also need to change the SSH base URL so the clone URL's in Stash are correct. See the SSH admin instructions.

### Developing for Stash

If you are a Stash plugin developer, please refer to our Stash developer documentation.

### Checking for known issues and troubleshooting the Stash upgrade

If something is not working correctly after you have completed the steps above to upgrade your Stash installation, please check for known Stash issues and try troubleshooting your upgrade as described below:

- Check for known issues. Known issues can be seen in the STASH project on our issue tracker.
- Stash Knowledge Base. Sometimes we find out about a problem with the latest version of Stash after we have released the software. In such cases we publish information in the Stash Knowledge Base.
- If you encounter a problem during the upgrade and cannot solve it, please create a support ticket and one of our support engineers will help you.