Install Bitbucket Server from an archive file
This page describes how to manually install Bitbucket Server from an archive file. However, we strongly recommend that you use the Bitbucket Server installer instead, for a quick and trouble-free install experience.
Related pages
- See Getting started, and consider using the installer
- Use Bitbucket in the enterprise
- Docker container image for Bitbucket Server
1. Check supported platforms
Check the Supported platforms page for details of the application servers, databases, operating systems, web browsers and Java and Git versions that we have tested Bitbucket Server with and recommend.
Atlassian only officially supports Bitbucket Server running on x86 hardware and 64-bit derivatives of x86 hardware.
Cygwin Git is not supported. No internal testing is done on that platform, and many aspects of Bitbucket Server's functionality (pull requests and forks among them) have known issues.
2. Check your version of Java
In a terminal or command prompt, run this:
java -versionThe version of Java should be 1.8.x . You'll need a 64-bit version of Java if you have a 64-bit operating system.
3. Check your versions of Git and Perl
In a terminal or command prompt, run:
git --version
perl --versionThe version of Git should be 1.8.x or higher. The version of Perl should be 5.8.8 or higher.
If you don't see supported versions of Git and Perl, either install or upgrade them – see Installing and upgrading Git.
4. Now it's time to get Bitbucket Server 
Download Bitbucket Server from the Atlassian download site. Looking for the Bitbucket Server WAR file?
Extract the downloaded file to an install location (without spaces in the path).
The path to the extracted directory is referred to as the in these instructions.<Bitbucket Server installation directory>
Never unzip the Bitbucket Server archive file over the top of an existing Bitbucket Server installation – each version of Bitbucket Server includes versioned jar files, such as bitbucket-model-4.0.0.jar . If you copy these, you end up with multiple versions of Bitbucket Server's jar files in the classpath, which leads to runtime corruption.
Note that you should use the same user account to both extract Bitbucket Server and to run Bitbucket Server (in Step 6.) to avoid possible permission issues at startup. For production installations, we recommend that you create a new dedicated user that will run Bitbucket Server on your system. See Running Bitbucket Server with a dedicated user.
5. Tell Bitbucket Server where to store your data
The Bitbucket Server home directory is where your Bitbucket Server data is stored.
If you are upgrading Bitbucket Server, simply update the value of BITBUCKET_HOME in the <Bitbucket Server installation directory>/bin/set-bitbucket-home file so the new Bitbucket Server installation points to your existing Bitbucket Server home directory (if you use a BITBUCKET_HOME environment variable to specify the home directory location, no change is required).
Otherwise, for a new install, 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:
#
if ["x${BITBUCKET_HOME}" = "x"]; then
export BITBUCKET_HOME="/home/username/bitbucket_home"
fiYou should not locate your Bitbucket home directory inside the
— they should be entirely separate locations. If you do put the home directory in the <Bitbucket Server installation directory> <Bitbucket Server installation directory> it may be overwritten, and lost, when Bitbucket Server gets upgraded. And by the way, you'll need separate Bitbucket Server home directories if you want to run multiple instances of Bitbucket Server.
6. Move server.xml to your Bitbucket Server home shared directory
If this is a new installation, or you are already running Stash 3.8 or above, you can skip to the next step.
If you are upgrading from Stash 3.7 or earlier and you made any changes to <Bitbucket Server installation directory>/conf/server.xml (for instance to secure your server with SSL):
- In the
<BITBUCKET_HOME>directory, make a new directory calledshared. - Then, copy your modified server.xml file into
<BITBUCKET_HOME>/shared/. Ensure the copied file is readable by the user account that runs Bitbucket Server.
7. (Optional) Install and configure a remote search server
Bitbucket Server 4.5+ comes with a bundled search server, which runs as a separate process from the Bitbucket Server application, and does not require any extra configuration.
If you plan to use the bundled search server, jump to the next step, Start Bitbucket Server!
However, you can also install a search server on a remote machine, which can provide some advantages allocating memory resources. Read the instructions for installing and configuring a remote search server at Install and configure a remote Elasticsearch server and Install and configure a remote OpenSearch server.
Bundled search server ports
Bitbucket Server's bundled search server requires ports 7992 and 7993 be available to provide code search functionality. This is not configurable, so ensure these ports are available.
8. Start Bitbucket Server!
There are a couple of ways in which you can start Bitbucket Server – see Start and stop Bitbucket.
If you've setup a remote search server you do not want to start the bundled search server.
To start Bitbucket Server with a remote search server
When using a remote search server, instead of the bundled search server, start Bitbucket Server by running start-bitbucket.sh --no-search. This starts Bitbucket Server alone without running the bundled search server.
Finish configuring Bitbucket Server
Now, in your browser, go to http://localhost:7990/ and run through the Setup Wizard. In the Setup Wizard:
- If you're evaluating Bitbucket Server, select Internal at the 'Database' step. Bitbucket Server will use its internal database, and you can easily migrate to external database later. See Connect Bitbucket to an external database.
- Enter your Bitbucket Server license key.
- Set the base URL for Bitbucket Server.
- Set up an administrator account.
- You can set up Jira Software integration, but you can do this later if you wish. See Configuring Jira integration in the Setup Wizard .
9. Set up your mail server
Configure your email server so users can receive a link from Bitbucket Server that lets them generate their own passwords. See Setting up your mail server.
10. Add users and repositories
Now is the time to set up your users in Bitbucket Server, and to tell Bitbucket Server about any existing repositories you have. Please the following pages for the details:
Additional steps for production environments
For production or enterprise environments we recommend that you configure the additional aspects described on Use Bitbucket in the enterprise. The aspects described there are not necessary when you are installing for evaluation purposes only.
If you wish to install Bitbucket Server as a service on Linux, see Run Bitbucket as a Linux service.
Stopping Bitbucket Server
Uninstalling Bitbucket Server
To uninstall Bitbucket Server, stop Bitbucket Server as described above and then delete the <Bitbucket Server installation directory> and Set the home directory.