Set the home directory

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

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

On this page:

What is the home directory?

The home directory is where your Bitbucket 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 installation directory>\bin\set-bitbucket-home.bat
  • Linux and Mac: <Bitbucket installation directory>/bin/set-bitbucket-home.sh

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

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

Your home directory contains the following directories and files:

PathDescription
caches

Contains 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 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.
log

Contains log files for Bitbucket.

shared/plugins

Contains plugin related data (such as externally uploaded plugins) for Bitbucket.

tmp

Contains temporary files created by the system. Its contents can safely be deleted when Bitbucket Data Center and Server is not running.

shared/bitbucket.properties

Allows configuring various aspects of how Bitbucket 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 Configuration properties for more information.

Setting the home directory

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

Only when you are installing 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 home directory (without spaces in the name), and then tell Bitbucket where you created it by editing the <Bitbucket 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 home directory, and then tell Bitbucket 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 home directory as the Variable value. Don't use a trailing backslash.

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

  • You should not locate your home directory inside the <Bitbucket installation directory> - they should be entirely separate locations. If you do put the home directory in the <Bitbucket installation directory> it will be overwritten, and lost, when Bitbucket gets upgraded. And, by the way, you can't use the same home directory for multiple instances of Bitbucket.
  • Keep the path length to the 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 home directory.


Securing the 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 (not a root/administrator user)
    • If you wish to run Bitbucket on port 80, use a separate http front end as described in Integrate Bitbucket 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 Bitbucket can access the 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, where "managed by Bitbucket" are the operative words. The repositories are for Bitbucket to interact with, and they are configured and managed accordingly. They are not a mechanism for configuring Bitbucket 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 releases. Bitbucket 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'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 home directory will result in the system being locked (briefly) on startup while Bitbucket 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 home location which will not need to be changed later.

Last modified on Aug 31, 2022

Was this helpful?

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