Cloud
Data Center 5.0
Versions

Install Bitbucket Server from an archive file

Bitbucket Server installation guide

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

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

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. When running Bitbucket Server on Windows, always use msysGit.

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"

On Windows, 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

Bitbucket Server uses the JAVA_HOME environment variable to find Java. To check that, in a command prompt, run:

echo %JAVA_HOME%

You should see a path to the root directory of the Java installation. When running Bitbucket Server on Windows, unlike Linux or Unix, JAVA_HOME paths with spaces are just fine.

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

Windows 7 ...

Stage 1. Locate the JRE installation directory

If you already know the installation path for the Java Runtime Environment, go to Stage 2 below. Otherwise, find the installation path by following these instructions:

  1. If you didn't change the installation path for the Java Runtime Environment during installation, it will be in a directory under C:\Program Files\Java. Using Explorer, open the directory C:\Program Files\Java.
  2. Inside that path will be one or more subdirectories such as C:\Program Files\Java\jre8. 

Stage 2. Set the JAVA_HOME variable

  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 "JAVA_HOME" as the Variable name, and the absolute path to where you installed Java as the Variable value. Don't use a trailing backslash, and don't wrap the value in quotes.

Now, in a new command prompt,  try running '%JAVA_HOME%\bin\java -version'. You should see the same version of Java as you saw in 2. above.

Windows Server 2003 R2 ...

Stage 1. Locate the JRE installation directory

If you already know the installation path for the Java Runtime Environment, go to Stage 2 below. Otherwise, find the installation path by following these instructions:

  1. If you didn't change the installation path for the Java Runtime Environment during installation, it will be in a directory under C:\Program Files\Java. Using Explorer, open the directory C:\Program Files\Java.
  2. Inside that path will be one or more subdirectories such as C:\Program Files\Java\jre8. 

Stage 2. Set the JAVA_HOME variable

Once you have identified the JRE installation path:

  1. Right-click the My Computer icon on your desktop and select Properties.
  2. Click the Advanced tab.
  3. Click the Environment Variables button.
  4. Under System Variables, click New.
  5. Enter the variable name as JAVA_HOME.
  6. Enter the variable value as the installation path for the Java Development Kit. Don't use a trailing backslash, and don't wrap the value in quotes.

    • If your Java installation directory has a space in its path name, you should use the shortened path name (e.g. C:\Progra~1\Java\jre7) in the environment variable instead.

      Note for Windows users on 64-bit systems

      Progra~1 = 'Program Files'
      Progra~2 = 'Program Files(x86)'

  7. Click OK.
  8. Click Apply Changes.
  9. Close any command window which was open before you made these changes, and open a new command window. There is no way to reload environment variables from an active command prompt. If the changes do not take effect even after reopening the command window, restart Windows.

Now, in a new command prompt,  try running '%JAVA_HOME%\bin\java -version'. You should see the same version of Java as you saw in 2. above.

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 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 <Bitbucket Server installation directory> in these instructions.

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/setenv 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 (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 Server installation directory>  — they should be entirely separate locations. If you do put the home directory in the <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.

Click here for Windows notes...

Tell Bitbucket Server where you created it by setting a BITBUCKET_HOME environment variable, for Windows 7, as follows:

  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 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:

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):

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

7. (Optional) Install and configure a remote Elasticsearch instance

Bitbucket Server 4.5+ comes with an bundled Elasticsearch instance, 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 Elasticsearch instance, jump to the next step, Start Bitbucket Server! 

However, you can also install Elasticsearch on a remote machine, which can provide some advantages allocating memory resources. Read the instructions for installing and configuring a remote Elasticsearch instance here: Install and configure a remote Elasticsearch instance.

Elasticsearch ports

Bitbucket Server's bundled Elasticsearch instance 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 Starting and stopping Bitbucket Server.

If you've setup a remote Elasticsearch instance you probably do not want to start the bundled Elasticsearch instance.

To start Bitbucket Server with a remote Elasticsearch instance

When using a remote Elasticsearch instance, instead of the bundled Elasticsearch instance, start Bitbucket Server by running start-webapp.sh instead of start-bitbucket.sh. This starts Bitbucket Server alone without running the bundled Elasticsearch instance.

Finish configuring Bitbucket Server

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 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 Using Bitbucket Server 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 or Windows, see either of:

 

Stopping Bitbucket Server

See Starting and 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 Bitbucket Server home directory.

Last modified on Feb 6, 2019

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.