Stash is now known as Bitbucket Server.
See the

Unknown macro: {spacejump}

of this page, or visit the Bitbucket Server documentation home page.

What is the Stash home directory?

The Stash home directory is created automatically by the Stash installer – see Getting started. The information on this page only applies if you are manually installing or upgrading Stash.

 

The Stash home directory is where your Stash data is stored. The home directory location is defined either by the STASH_HOME environment variable, or in the STASH_HOME line of:

  • <Stash installation directory>\bin\setenv.bat, on Windows
  • <Stash installation directory>/bin/setenv.sh, on Linux and Mac.

(warning) You should not locate your Stash home directory inside the <Stash installation directory> — they should be entirely separate locations. If you do put the home directory in the <Stash installation directory> it will be overwritten, and lost, when Stash gets upgraded. And by the way, you'll need separate Stash home directories if you want to run multiple instances of Stash.

(warning) Where possible, you should choose a location for your Stash home directory that will never need to be moved. Some home contents are location-sensitive, so moving the home directory may corrupt them. Stash attempts to update contents when it detects that the home directory has moved, but the safest approach is to avoid the issue altogether by leaving the home directory in the same location.

What does the Stash home directory contain?

Your Stash home directory contains the following directories and files:

PathDescription
cachesContains cache and index files. It should be safe for these files to be deleted between application restarts; however, these files must not be modified or deleted while Stash is running.
configContains application configuration.
dataContains the Git repositories, project avatars, and the embedded HSQL database if an external database is not configured.
exportContains dump files produced during database migrations.
libAs of Stash 2.1, can contain third-party jars such as the MySQL JDBC driver.
lib/nativeAs of Stash 2.1, can contain native libraries, such as Tomcat's APR-based native library.
logContains log files for Stash.
pluginsContains plugin related data (such as externally uploaded plugins) for Stash.
tmpContains temporary files created by the system. Its contents can safely be deleted when Stash is not running.
stash-config.propertiesAllows configuring various aspects of how Stash behaves, such as its database connection pool size and the location of the Git binary to use. This file will be created automatically during a database migration. It can be created manually otherwise. See Stash config properties for further information.

Notice that since Stash 3.2 the directories config, data and plugins as well as the file stash-config.properties were moved into shared, so you will find them under $STASH_HOME/shared.

Setting the Stash home directory

Note that the Stash home directory is created automatically by the Stash installer – see Getting started.

Only when you are installing Stash from an archive file will you need to set the value of STASH_HOME yourself, as described in this section.

The Stash home directory is where your Stash data is stored.

Create your Stash home directory (without spaces in the name), and then tell Stash where you created it by editing the <Stash installation directory>/bin/setenv.sh file – uncomment the STASH_HOME line and add the absolute path to your home directory. Here's an example of what that could look like when you're done:

The Stash home directory is where your Stash data is stored.

Create your Stash home directory, and then tell Stash where you created it by setting a STASH_HOME environment variable, as follows.

For Windows 7:

  1. Go to Start, search for "sys env" and choose Edit the system environment variables.
  2. Click Environment Variables, and then New under 'System variables'.
  3. Enter "STASH_HOME" as the Variable name, and the absolute path to your Stash home directory as the Variable value. Don't use a trailing backslash.

There are a few things to know about setting up the Stash home directory on Windows that will make life easier:

  • You should not locate your Stash home directory inside the  <Stash installation directory> — they should be entirely separate locations. If you do put the home directory in the  <Stash installation directory> it will be overwritten, and lost, when Stash gets upgraded. And, by the way, you can't use the same Stash home directory for multiple instances of Stash.
  • Keep the path length to the Stash home directory as short as possible. See Stash always shows incorrect Merge Conflict in PRs for an explanation.
  • Don't use spaces in the path to the Stash home directory.

 

Securing the Stash home directory

The internal database files, the migration dump files and stash-config.properties all contain information that may be considered secret (server settings, salted and hashed user passwords, database passwords, etc).

For production use, we strongly recommend that you secure this directory against unauthorised access. 

We recommend the following precautions:

  • Assign a separate restricted user account on the machine for running Stash (not a root/administrator user)
    • If you wish to run Stash on port 80, use a separate http front end as described in Integrating Stash with Apache HTTP Server (do not run as root/Administrator if security of the home directory is important to you)
  • Ensure that only the user running Stash can access the Stash home directory, and that this user has read, write and execute permissions, by setting file system permissions appropriately for your operating system.

About the repositories

As noted above, data contains the Git repositories being managed by Stash, where "managed by Stash" are the operative words. The repositories are for Stash to interact with, and they are configured and managed accordingly. They are not a mechanism for configuring Stash behaviour. We strongly recommend that customers never modify them, nor interact with them directly. They are intentionally structured in a way which does not lend itself well to direct interaction.

Being Git repositories, there are certainly standard aspects to how the repositories on disk are stored and how they function. However, the exact way they are configured can and does change between Stash releases. Stash makes no effort to preserve unexpected configuration changes which have been applied by customers, and such changes may cause failures at runtime or during upgrades. If there is an aspect of Stash's behaviour you wish to configure, please open a feature request on jira.atlassian.com rather than trying to modify the repositories directly.

Repositories are location sensitive. Moving your Stash home directory will result in the system being locked (briefly) on startup while Stash updates the repositories on disk. Assuming the updates are applied successfully, the system will then unlock itself for normal usage.

Where possible, please choose a Stash home location which will not need to be changed later.

 

 

 

 

 Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.