Bitbucket Server home directory
What is the Bitbucket home directory?
The Bitbucket home directory is created automatically by the Bitbucket Server installer – see Getting started to install and start using Bitbucket Server.
The information on this page only applies if you are manually installing or upgrading Bitbucket Server.
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\setenv.bat - Linux and Mac:
<Bitbucket Server installation directory>/bin/setenv.sh
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>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).
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.
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:
| Path | Description |
|---|---|
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 Server is running. |
shared/config | Contains application configuration. |
shared/data | Contains the Git repositories, project avatars, and the embedded HSQL database if an external database is not configured. |
export | Contains dump files produced during database migrations. |
lib | Can contain third-party jars such as the MySQL JDBC driver. |
lib/native | Can contain native libraries, such as Tomcat's APR-based native library. |
log | Contains log files for Bitbucket Server. |
shared/plugins | Contains plugin related data (such as externally uploaded plugins) for Bitbucket Server. |
tmp | Contains temporary files created by the system. Its contents can safely be deleted when Bitbucket Server is not running. |
shared/bitbucket.properties | Allows 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 further information. |
Setting the Bitbucket home directory
Note that the Bitbucket home directory is created automatically by the Bitbucket Server installer – see Getting started.
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.
The Bitbucket Server home directory is where your Bitbucket Server data is stored.
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/setenv.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:
The Bitbucket Server home directory is where your Bitbucket Server data is stored.
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:
- Go to Start, search for "sys env" and choose Edit the system environment variables.
- Click Environment Variables, and then New under 'System variables'.
- 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><Bitbucket Server installation directory> - 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 unauthorised access.
We recommend the following precautions:
- Assign a separate restricted user account on the machine for running Bitbucket Server (not a root/administrator user)
- If you wish to run Bitbucket Server on port 80, use a separate http front end as described in Integrating Bitbucket Server 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 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 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 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 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 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.