Moving your STASH_HOME directory out of your Bitbucket Server installation directory

Summary

Prior to Bitbucket Server 3.5.0, it was possible to set the BITBUCKET_HOME directory, which is used to store application data (e.g. repositories, logs, caches and plugins) as the same directory as or a subdirectory of the installation directory, where binaries, jars and scripts are stored for running Bitbucket Server. Doing so causes a number of problems including:

• Increased pain during upgrades as the Bitbucket Server installation directory will be changed or replaced but will point to the existing home directory

• Classpath corruption due to conflicts between the BITBUCKET_HOME/lib and the BITBUCKET_INST/lib

For more information, see BSERV-5259 - Stash does not protect against using the Stash installation directory as the home directory

In order to prevent these sort of problems occurring, as of Bitbucket Server 3.5 the BITBUCKET_HOME directory must be outside the installation directory.

Solution

Moving a BITBUCKET_HOME directory which is a subdirectory of the installation

This is a relatively straight forward process:

1. Create a directory outside of the Bitbucket Server installation directory

2. Copy the contents of your current home directory into your new home directory

3. Update setenv.sh/setenv.bat or your environment configurations so that the BITBUCKET_HOME environment variable points to the new directory

Extracting the BITBUCKET_HOME directory which was set as the same directory as the installation

This process for this is a little more involved:

1. Create a directory outside of the Bitbucket Server installation directory

2. Copy over the shared/ (if it exists), caches/, plugins/ and data/ (if it exists) directories from your old home directory to your new home directory

3. Copy your bitbucket.properties (if it exists) from your old home directory to your new home directory

4. Create a lib/ directory in your new home directory and copy any JDBC drivers which you placed in your old lib/ directory

5. Update setenv.sh/setenv.bat or your environment configurations so that the BITBUCKET_HOME environment variable points to the new directory

setenv and environment variable changes in Bitbucket Server 5.0+

Starting with Bitbucket Server 5.0, setenv.sh and setenv.bat have been removed. The options that were set in this file can now be set via environment variables. Where to set the environment variable depends on which Operating System you're running on.

Linux

When using the atlbitbucket service on Linux, the environment variables are ignored. You must set the parameters in _start-webapp.sh (or start-bitbucket.sh). These values will be read when the service starts.

As an example, to set JVM_SUPPORT_RECOMMENDED_ARGS, you would add this line to the file:

Example

Windows

Set the parameter as an environment variable for the user running Bitbucket Server. For example, if you want to set JVM_SUPPORT_RECOMMENDED_ARGS, create it as an environment variable and assign the appropriate value to it. When Bitbucket Server starts using the startup scripts or service, it will pick up and apply this value.