Migrating Stash to another server

1. Prepare for the migration

In preparation for migrating Stash to another server, check that you have done the following:

• Confirm that the operating system, database, other applicable platforms and hardware on the new machine will comply with the requirements for Stash.
• Check for any known migration issues in the Stash Knowledge Base.
• Alert users to the forthcoming Stash service outage.
• Ensure that users will not be able to update existing Stash data during the migration. You can do this by temporarily changing the access permissions for Stash.
• Make sure you have created a user in Stash (not in your external user directory) that has System Administrator global permissions so as to avoid being locked out of Stash in case the new server does not have access to your external user directory.

2. Move the Stash data to a different machine

This section gives a brief overview of how to move the Stash data to a different machine. You do not need to do anything in this section if you will continue to use the embedded database - the Stash data is moved when you move the Stash installation.

The Stash data includes the data directories (including the Git repositories), log files, installed plugins, temporary files and caches.

You can move the Stash data:

• from the embedded database to a supported external DBMS.
• to another instance of the same DBMS.
  
• from one DBMS to another supported DBMS (for example, from MySQL to PostgreSQL).

You can also move the actual DBMS. Atlassian recommends that for large installations, Stash and the DBMS run on separate machines.

There are 2 steps:

1. Create and configure the DBMS in the new location. Please refer to Connecting Stash to an external database, and the relevant child page, for more information.
2. Either:
   
   • If the new location is currently visible to Stash, use the Stash Database Migration Wizard. Please refer to Connecting Stash to an external database, and the relevant child page, for more information. 
   • If the new location is not currently visible to Stash (perhaps because you are moving to a new hosting provider), you need to perform a database export and then import the backup to the new DBMS. Please refer to the vendor documentation for your DBMS for detailed information.
     You will also need to update the stash-config.properties file in the <Stash home directory> as described below.

3. Move Stash to a different machine

This section describes moving the Stash installation to a different machine.

1. Stop Stash. See Starting and stopping Stash.
2. Make an archive (such as a zip file) of the Stash home directory. The home directory contains data directories (including the Git repositories), log files, installed plugins, temporary files and caches. 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.

3. Copy the archive of the Stash home directory to the new machine and unzip it to its new location there.

   • For production environments the Stash home directory should be secured against unauthorised access. See Stash home directory.

   • When moving the Stash home directory from Windows to Linux or Mac, make sure that the files in the <Stash home directory>/git-hooks and <Stash home directory>/shared/data/repositories/<repoID>/hooks directories have the executable file permission set.
4. Set up an instance of Stash in the new location by doing one of the following:
   
   • Make an archive of the old Stash installation directory and copy it across to the new machine.
   • Install the same version of Stash from scratch on the new machine.
5. Redefine the value for STASH_HOME, mentioned in Step 2. above, in the new <Stash installation directory>, using the new location for your copied home directory. See Stash home directory for more information.
6. If you are continuing to use the Stash embedded database, or you used the Migration Wizard to move the Stash data, you should now be able to start Stash on the new machine and have all your data available. See Starting and stopping Stash. Once you have confirmed that the new installation of Stash is working correctly, revert the access permissions for Stash to their original values.
7. If you moved the Stash data by performing a database export and import, carry on to Step 4. below to update the stash-config.properties file in the <Stash home directory>.

4. Update the Stash configuration

If you moved the Stash data by performing a database export, you must update the stash-config.properties file in the <Stash home directory> with the changed configuration parameters for the database connection.

The configuration parameters are described in Stash config properties.

Once the configuration parameters are updated, you should be able to start Stash on the new machine and have all your data available. See Starting and stopping Stash. Once you have confirmed that the new installation of Stash is working correctly, revert the access permissions for Stash to their original values.