Install Bitbucket Server on Linux from an archive file

Install Bitbucket Server on Linux

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This page describes how to install Bitbucket Server in a production environment, with an external database, manually using a tar.gz file.

This method gives you the most control of the installation process.



Other ways to install Bitbucket Server: 

  • Trial - get a free trial up and running in no time.
  • Installer – install Bitbucket using the Linux installer.

On this page

Before you begin

Before you install Bitbucket Server, there are a few questions you need to answer. 

Are you using a supported operating system and Java version?
Tell me more...

Check the Supported Platforms page for the version of Bitbucket Server you are installing. This will give you info on supported operating systems, databases and browsers.

Good to know:

  • We don't support installing Bitbucket Server on macOS for production sites.
  • The Bitbucket Server installer includes Java (JRE) and Tomcat, so you don't need to install these separately.
Do you want to run Bitbucket Server as a service?
Tell me more...

Running Bitbucket Server as a service means that Bitbucket Server will automatically startup when your Linux server is started.

You should use the Linux installer if you want to run Bitbucket Server as a service.

If you choose not to run Bitbucket Server as a service:

  • You will start and stop Bitbucket Server by running the start-bitbucket.sh file in your Bitbucket Server installation directory.
  • Bitbucket Server will be run as the user account that was used to install Bitbucket Server, or you can choose to run as a dedicated user.
  • Bitbucket Server will need to be restarted manually if your server is restarted.

For more information about these options, see the pages:

Bitbucket uses ports 7990, 7992, and 7993 by default, are they available?
Tell me more...

Port 7990: Bitbucket runs on port 7990 and on port 7999 for SSH by default. If this port is already in use, see Change the port Bitbucket listens on for more guidance on changing this.

Ports 7992 and 7993: Bitbucket Server's bundled search server, which is required for search functionality, requires ports 7992 and 7993 be available. This is not configurable, so ensure these ports are available.

Is your database set up and ready to use?
Tell me more...

To run Bitbucket in production you'll need an external database. Check the Supported platforms page for the version you're installing for the list of databases we currently support.

Good to know:

Do you have a Bitbucket Server license?
Tell me more...

You'll need a valid license to use Bitbucket Server.

Good to know:

  • If you don't have a license you can create an evaluation license during setup, and be sure to use your business email address.
  • If you already have a license key you'll be prompted to log in to my.atlassian.com to retrieve it, or you can enter the key manually during setup.
  • If you're migrating from Bitbucket Cloud (bitbucket.org), you'll need a new license.

Do you have Git and Perl installed and on the right version?
Tell me more...

Bitbucket Server requires Git on the machine that will run Bitbucket Server. If you need to check, install, or upgrade Git on the Bitbucket Server instance machine, see Installing and upgrading Git.

Do not upgrade Git to the latest version until you check the Supported Platforms page for which version of Git is currently supported.

Check that you have all the other system requirements, including Perl, to avoid any trouble.

Is your JAVA_HOME variable set correctly?
Tell me more...

Before you install Bitbucket Server, check that you're running a supported Java version and that the JAVA_HOME environment variable is set correctly.

To check the JAVA_HOME variable:

$ java -version

To check your JAVA_HOME variable is set correctly:

$ echo $JAVA_HOME

If you see a path to your Java installation directory, the JAVA_Home environment variable has been set correctly. If a path is not returned you'll need to set your JAVA_HOME environment variable manually before installing Bitbucket Server.

Do you need to use a remote search server?
Tell me more...

Bitbucket Server comes with a bundled search server, which runs as a separate process from the Bitbucket Server application and doesn't require any extra configuration.

You can can also install a search server on a remote machine, which can provide some advantages allocating memory resources. In most cases you're better off using our bundled search server that will be automatically configured out of the box.

A clustered Bitbucket Data Center installation requires a search server on a remote machine.

If you still want to use a search server on a remote machine, there are instructions for doing so on the the Install and configure a remote Elasticsearch server and Install and configure a remote OpenSearch server pages.



Install Bitbucket Server

1. Download Bitbucket Server

Download the tar.gz file - www.atlassian.com/software/bitbucket/download.

2. Create the installation directory

  1. Create your installation directory (with full control permission) – this is where Bitbucket will be installed. Avoid using spaces or special characters in the path. We'll refer to this directory as your <installation-directory>.

  2. Extract the tar.gz file to your <installation-directory>

3. Create the home directory

  1. Create your home directory (with full control permission) – this is where your Bitbucket Server data is stored. This should be separate to your installation directory. We'll refer to this directory as your <home-directory>

  2. Edit <installation-directory>/bin/set-bitbucket-home.sh file – uncomment the BITBUCKET_HOME line and add the absolute path to your home directory.

4. Start Bitbucket

  1. Change directory to the <installation-directory> and run this command:

    bin/start-bitbucket.sh
  2. In your browser, go to http://localhost:7990/ and run through the Setup Wizard. 

Set up Bitbucket

The Setup Wizard runs automatically when you visit Bitbucket Server in your browser the first time it's started.

5. Connect to your database 

  1. If you've not already done so, it's time to create your database. See the 'Before you begin' section of this page for details. 

Select External as your database, then choose a Database Type from the dropdown menu and enter the details of your database.

If you plan to use MySQL, there's an extra step...

The JDBC drivers for MySQL / MariaDB are not bundled with Bitbucket Server (due to licensing restrictions), so you need download and install the driver.

  1. Download the MySQL Connector/J JDBC driver from the download site.
  2. Expand the downloaded zip/tar.gz file.
  3. Copy the .jar file from the extracted directory to your <Bitbucket home directory>/lib directory.
  4. Restart Bitbucket server.

Also see Connecting Bitbucket Server to MySQL.

6. Add your license key

Follow the prompts to log in to my.atlassian.com to retrieve your license, or enter a license key.

You can also set the base URL at this step, (you can elect to do this later).

7. Create your administrator account

  1. Enter details for the administrator account.
  2. Select either Go to Bitbucket to go straight to the Bitbucket interface or Integrate with Jira to create your connection with an existing Jira application. 

    Tell me more...

    You can also select to use a Jira application as your user database during this step. See the page Configuring Jira integration in the Setup Wizard for details. You can also do this later.

9. Start using Bitbucket Server

That's it! Your Bitbucket site is accessible from a URL like this: http://<computer_name_or_IP_address>:<port>

What's next?

When setting up Bitbucket in a production environment, we recommend that you configure these aspects next:


Read more about setting up Bitbucket for an enterprise here: Using Bitbucket in the enterprise.

Last modified on Nov 24, 2022

Was this helpful?

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