Install Bitbucket Data Center from an archive file

This page describes how to manually install Bitbucket Data Center from an archive file. However, we strongly recommend that you use the Bitbucket installer instead, for a quick and trouble-free install experience.

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 Data Center with and recommend.

Atlassian only officially supports Bitbucket Data Center 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 Data Center 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 -version

The 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.

On Linux, if you don't see a supported version, then get Java...

Install Java

Download Java Server JRE from Oracle's website, and install it.

Now try running 'java -version' again to check the installation. The version of Java should be  1.8.x.

Check that the system can find Java

In a terminal, run this:

echo $JAVA_HOME

You should see a path like /usr/jdk/jdk1.8.0.

If you don't see a path, then set JAVA_HOME

Do one of the following:

  • If JAVA_HOME is not set, log in with 'root' level permissions and run:

    echo JAVA_HOME="path/to/JAVA_HOME" >> /etc/environment

    where  path/to/JAVA_HOME may be like: /usr/jdk/jdk1.8.0

  • If JAVA_HOME needs to be changed, open the  /etc/environment file in a text editor and modify the value for JAVA_HOME to:
    JAVA_HOME="path/to/JAVA_HOME"                    

    It should look like: /usr/jdk/jdk1.8.0

On macOS, if you don't see a supported version, then get Java...

Install Java

Download Java Server JRE from Oracle's website, and install it.

Now try running 'java -version' again to check the installation. The version of Java should be 1.8.x .

Check that the system can find Java

In a terminal, run this:

echo $JAVA_HOME
You should see a path like /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/.

If you don't see a path, then set JAVA_HOME

Open your ~/.profile file in a text editor and insert:

JAVA_HOME="path/to/JAVA_HOME"
export JAVA_HOME

where path/to/JAVA_HOME may be like: /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home/

Refresh your ~/.profile in the terminal and confirm that JAVA_HOME is set:

source ~/.profile
$JAVA_HOME/bin/java -version

You should see a version of Java that is 1.8.x, like this:

java version "1.8.0_1"

3. Check your versions of Git and Perl

In a terminal or command prompt, run:

git --version
perl --version

The 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 Data Center

Download Bitbucket Data Center from the Atlassian download site. Looking for the Bitbucket 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 <Bitbucket installation directory> in these instructions.

Never unzip the Bitbucket Data Center archive file over the top of an existing Bitbucket Data Center installation –  each version of Bitbucket Data Center includes versioned jar files, such as  bitbucket-model-4.0.0.jar . If you copy these, you end up with multiple versions of Bitbucket Data Center jar files in the classpath, which leads to runtime corruption.

Note that you should use the same user account to both extract Bitbucket Data Center and to run Bitbucket Data Center (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 Data Center on your system. See Running Bitbucket Data Center with a dedicated user.

5. Tell Bitbucket Data Center where to store your data

The Bitbucket Data Center home directory is where your data is stored.

If you are upgrading Bitbucket Data Center, simply update the value of BITBUCKET_HOME in the <Bitbucket installation directory>/bin/set-bitbucket-home file so the new Bitbucket Data Center installation points to your existing Bitbucket Data Center 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 Data Center where you created it by editing the <Bitbucket installation directory>/bin/set-bitbucket-home.sh (or set-bitbucket-home.bat) 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"
fi

You should not locate your Bitbucket 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 may be overwritten, and lost, when Bitbucket Data Center gets upgraded. And by the way, you'll need separate Bitbucket Data Center home directories if you want to run multiple instances of Bitbucket Data Center.

6. Move server.xml to your Bitbucket Data Center home shared directory

If this is a new installation, or you are already running Stash 3.8 or later, you can skip to the next step.

If you are upgrading from Stash 3.7 or earlier and you made any changes to <Bitbucket installation directory>/conf/server.xml (for instance to secure your server with SSL):

  1. In the <BITBUCKET_HOME> directory, make a new directory called shared.
  2. Then, copy your modified server.xml file into <BITBUCKET_HOME>/shared/. Ensure the copied file is readable by the user account that runs Bitbucket Data Center.

7. Install and configure a remote search server

This step is mandatory if you're using a clustered Bitbucket Data Center instance. 

If your instance is single-node, this step is optional. On a single-node instance, you can use bundled search.

Bitbucket 4.5+ comes with a bundled search server, which runs as a separate process from the Bitbucket application, and does not require any extra configuration. 

If you plan to use the bundled search server, jump to the next step, Start Bitbucket Data Center! 

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 Data Center 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 Data Center!

There are a couple of ways in which you can start Bitbucket Data Center – 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 Data Center with a remote search server

When using a remote search server, instead of the bundled search server, start Bitbucket Data Center by running start-bitbucket.sh --no-search. This starts Bitbucket Data Center alone without running the bundled search server.

Finish configuring Bitbucket Data Center

Now, in your browser, go to http://localhost:7990/ and run through the Setup Wizard. In the Setup Wizard:

9. Set up your mail server

Configure your email server so users can receive a link from Bitbucket Data Center 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 Data Center, and to tell Bitbucket Data Center 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 Data Center as a service on Linux, see Run Bitbucket as a Linux service.

 

Stopping Bitbucket Data Center

See Start and stop Bitbucket.

Uninstalling Bitbucket Data Center

To uninstall Bitbucket Data Center, stop Bitbucket Data Center as described above and then delete the <Bitbucket installation directory> and Set the home directory.

Last modified on Oct 18, 2023

Was this helpful?

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