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\ - Linux and Mac:
<Bitbucket installation directory>/bin/set-bitbucket-home.sh
Bitbucket 4.0 and later versions don't allow the home directory to be the same directory as, or a subdirectory of, the
. The home directory, as defined by the <Bitbucket installation directory> 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).
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.
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:
| 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 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. |
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.
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:
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.