Bitbucket Server home directory

The Bitbucket home directory is created automatically by the Bitbucket Server installer – see the Bitbucket Server installation guide to install and start using Bitbucket Server.

The information on this page only applies if you are manually installing or upgrading Bitbucket Server.

On this page:

What is the Bitbucket home directory?

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

  • Windows: <Bitbucket Server installation directory>\bin\set-bitbucket-home.bat
  • Linux and Mac: <Bitbucket Server installation directory>/bin/set-bitbucket-home.sh

(warning) Bitbucket Server 4.0 and later versions don't allow the Bitbucket Server home directory to be the same directory as, or a subdirectory of, the  <Bitbucket Server installation directory> . The Bitbucket home directory, as defined by the BITBUCKET_HOME variable, must be in a separate location – Bitbucket Server will fail on startup otherwise. And by the way, you'll need separate Bitbucket Server home directories if you want to run multiple instances of Bitbucket Server (when these are not nodes for a Bitbucket Data Center).

(warning) Where possible, you should choose a location for your Bitbucket home directory that will never need to be moved. Some home contents are location-sensitive, so moving the home directory may corrupt them. Bitbucket Server 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.

(warning) Where possible, do not configure Bitbucket Server instances to use a UNC path. This can cause issues forking and merging pull requests. Instead, map a network drive or use the mklink command to create a symbolic link to the networked location and update BITBUCKET_HOME  to reference the new drive letter/path.

What does the Bitbucket home directory contain?

Your Bitbucket 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 Bitbucket Server is running.
shared/configContains application configuration.
shared/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.
lib Can contain third-party jars such as the MySQL JDBC driver.
lib/nativeCan contain native libraries, such as Tomcat's APR-based native library.
logContains log files for Bitbucket Server.
shared/pluginsContains plugin related data (such as externally uploaded plugins) for Bitbucket Server.
tmpContains temporary files created by the system. Its contents can safely be deleted when Bitbucket Server is not running.
shared/bitbucket.propertiesAllows configuring various aspects of how Bitbucket Server 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 Bitbucket Server config properties for more information.

Setting the Bitbucket home directory

Note that the Bitbucket home directory is created automatically by the Bitbucket Server installer .

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

Click here if setting BITBUCKET_HOME on Linux or Mac...

Create your Bitbucket home directory (without spaces in the name), and then tell Bitbucket Server where you created it by editing the <Bitbucket Server installation directory>/bin/set-bitbucket-home.sh file – uncomment the BITBUCKET_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:

Click here if setting BITBUCKET_HOME on Windows...

Create your  Bitbucket Server home directory, and then tell Bitbucket Server where you created it by setting a BITBUCKET_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 "BITBUCKET_HOME" as the Variable name, and the absolute path to your Bitbucket home directory as the Variable value. Don't use a trailing backslash.

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

  • You should not locate your Bitbucket home directory inside the  <Bitbucket Server installation directory> — they should be entirely separate locations. If you do put the home directory in the  <Bitbucket Server installation directory> it will be overwritten, and lost, when Bitbucket Server gets upgraded. And, by the way, you can't use the same Bitbucket home directory for multiple instances of Bitbucket Server.
  • Keep the path length to the Bitbucket home directory as short as possible. See Bitbucket Server is unable to create the merge diff for pull requests for an explanation.
  • Don't use spaces in the path to the Bitbucket home directory.

 

Securing the Bitbucket home directory

The internal database files, the migration dump files and bitbucket.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 unauthorized access. 

We recommend the following precautions:

  • Assign a separate restricted user account on the machine for running Bitbucket Server (not a root/administrator user)
  • Ensure that only the user running Bitbucket Server can access the Bitbucket 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 Bitbucket Server, where "managed by Bitbucket Server" are the operative words. The repositories are for Bitbucket Server to interact with, and they are configured and managed accordingly. They are not a mechanism for configuring Bitbucket Server behavior. 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 Bitbucket Server releases. Bitbucket Server 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 Bitbucket Server's behavior 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 Bitbucket home directory will result in the system being locked (briefly) on startup while Bitbucket Server 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 Bitbucket Server home location which will not need to be changed later.

Last modified on Jan 4, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.