Install and configure a remote Elasticsearch server

This page describes how to configure a remote Elasticsearch server to work with Bitbucket Data Center.

Bitbucket Data Center requires a remote Elasticsearch server, as no search server is bundled or installed for Bitbucket Data Center. Elasticsearch is a supported search server distribution for Bitbucket Data Center.

Bitbucket Data Center can have only one remote connection to Elasticsearch for your cluster. This may be a standalone Elasticsearch installation or a clustered installation behind a load balancer. 

For details of about how Bitbucket uses the search server, including troubleshooting tips and frequently asked questions, see Administer code search.

Step 1: Install Elasticsearch on a remote machine

We don't provide specific instructions for installing Elasticsearch, but a good place to start is the Elasticsearch guide for installation. Elastic provides installation packages in several different formats here. Note that the authentication plugin – Buckler, described within the Secure Elasticsearch section – only supports specific versions of Elasticsearch. Refer to the Supported platforms - Additional Tools section to see the current Elasticsearch release we support.

Step 2: Configure Elasticsearch

The elasticsearch.yml file contains configuration details for your Elasticsearch server.

The location of your Elasticsearch configuration directory varies depending on how you installed Elasticsearch. For installations from an archive the configuration is $ES_HOME/config, while for packaged installations (e.g. from a deb or rpm package) the the configuration directory is typically /etc/elasticsearch.

To configure your remote Elasticsearch server

  1. Locate the elasticsearch.yml file within the configuration directory of your Elasticsearch server
  2. Add these properties to your elasticsearch.yml file:

    action.auto_create_index: ".watches,.triggered_watches,.watcher-history-*" false
    Third party plugins, such as Elastic's Shield plugin, may require specific exceptions to be set for action.auto_create_index. Consult your provider's documentation for more information.

Step 3: Secure Elasticsearch

You need to secure access to your remote Elasticsearch server with a username and password. We recommend securing your remote Elasticsearch server with a security plugin that requires anyone connecting to it to provide authentication credentials. Atlassian provides a free Elasticsearch plugin called Buckler for this purpose.

Follow the instructions below to secure your remote Elasticsearch server with the Buckler plugin.

Install the Buckler plugin

Select the version of Buckler that matches the version of Elasticsearch you are using. Versions of Elasticsearch not listed in the table below are not supported with Buckler, but may be still be supported for use with Bitbucket Data Center by using a different plugin to provide basic authentication, like Elastic's Shield plugin. For details on supported search server versions, see the Supported platforms page.

The URL for Buckler can be copied to your clipboard easily with right click > Copy Link Address.

Elasticsearch versionBuckler plugin

Elasticsearch 7.17.6

Buckler 3.1.0
Elasticsearch 7.16.3Buckler 3.0.1
Elasticsearch 7.16.2Buckler 3.0.0
Elasticsearch 7.10.2Buckler 2.1.5

Buckler can then be installed into your remote Elasticsearch server using the plugin helper in the Elasticsearch /bin directory:

./elasticsearch-plugin install -b "<link from table above>"

Configure basic authentication for Bitbucket to access your remote Elasticsearch installation. We strongly suggest enabling basic HTTP authentication, at minimum, for a remote Elasticsearch server working with Bitbucket Data Center.

  1. Create a directory called buckler within the Elasticsearch configuration directory. 
  2. Within the <Elasticsearch config>/buckler directory, create a file named buckler.yml

  3. To configure the Buckler for basic HTTP authentication, the following properties need to be added to buckler.yml. This includes selecting a username and password that Bitbucket will use to access Elasticsearch (which is configured in Bitbucket in a later step).

    <Elasticsearch config directory>/buckler/buckler.yml
    auth.basic.http.enabled: true
    auth.basic.username: <username>
    auth.basic.password: <password>
    Here's an example config which enables every feature...
    <Elasticsearch config directory>/buckler/buckler.yml
    auth.basic.http.enabled: true
    auth.basic.tcp.enabled: true
    auth.basic.username: admin
    auth.basic.password: basicpassword
    tls.http.enabled: true
    tls.tcp.enabled: true
    tls.keystore.path: /path/to/keystore
    tls.keystore.password: keystorepassword
    Here's an explanation of all the parameters you can configure...
    Enables basic authentication for HTTP.
    Enables basic authentication for TCP.
    Username to access Elasticsearch server.
    Password to access Elasticsearch server.
    Enables TLS for HTTP.
    Enables TLS for TCP.
    Absolute filesystem path to the keystore.
    Password for accessing the keystore.

    4. To configure Elasticsearch to use Buckler for security, the following properties need to be added to elasticsearch.yml:

    http.type: buckler
    transport.type: buckler

    5. Start your remote Elasticsearch server.

Step 4: Connect Elasticsearch to Bitbucket

If you're on a version lower than 7.21, refer to the documentation for that version.

Once you've configured your remote Elasticsearch server, you then need to connect it to Bitbucket. You can complete the following steps from your Bitbucket GUI or using the file. 

To configure your remote Elasticsearch server using the file:

Once a parameter is set in the file, it cannot be edited later from the admin UI. Any changes that need to be made to the Elasticsearch configuration must be made within the file and require a restart of Bitbucket to be applied.
  1. Locate the file in the <Bitbucket home directory>/shared directory. 
  2. Add the details of your Elasticsearch server (created in step 3.3 above):

    <Bitbucket home directory>/shared/<search server URL> #e.g. http://localhost:9200/<username><password
  3. Start (or restart) Bitbucket without starting the bundled search server.

    Bitbucket Data CenterBitbucket Data Center does not install the bundled search server, so will always start without it.
    Bitbucket Server on Linux (not a service) --no-search 
    Bitbucket Server on Linux (as a service)Modify your start service script to pass --no-search to

    Your remote Elasticsearch server is now configured to work with Bitbucket.

Last modified on May 22, 2024

Was this helpful?

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