How to Install and configure a remote Elasticsearch instance

Still need help?

The Atlassian Community is here for you.

Ask the community

This page describes how to provision a remote Elasticsearch instance to work with Bitbucket Data Center.

Bitbucket Data Center requires a remote Elasticsearch instance, as it is not bundled or installed 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 Elasticsearch, 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 instance.

To configure your remote Elasticsearch instance

  1. Locate the elasticsearch.yml file within the configuration directory of your Elasticsearch (6.8.6) instance. 
     
  2. Add these parameters to your elasticsearch.yml file

    action.auto_create_index: ".watches,.triggered_watches,.watcher-history-*"
    network.host: 0.0.0.0
    xpack.security.enabled: 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 instance with a username and password. We recommend securing your remote Elasticsearch instance with a security plugin that requires anyone connecting to it provides authentication credentials. Atlassian provides a free plugin called Buckler for this purpose. Bitbucket Server also supports authentication to Elasticsearch through other plugins that provide basic authentication, like Elastic's Shield plugin.


To secure your remote Elasticsearch instance with the Buckler plugin

Copy the Buckler plugin URL to your clipboard:

Elasticsearch versionBuckler plugin
Elasticsearch 7.16.2Buckler 3.0.0
Elasticsearch 7.9.3Buckler 2.1.4
Elasticsearch 7.5.2Buckler 2.1.3
Elasticsearch 6.8.6Buckler 2.1.2
Elasticsearch 6.8.22Buckler 2.2.0
Elasticsearch 6.6.1Buckler 2.1.1
Elasticsearch 6.5.3Buckler 2.0.1

Install the plugin onto your remote Elasticsearch instance 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 instance working with Bitbucket Data Center.

  1. Create a directory called buckler within the elasticsearch/config/ directory. 
  2. Within the elasticsearch/config/buckler directory, create a file named buckler.yml

    When installing using rpm or deb file

    The location of your configuration directory varies depending on how you installed Elasticsearch. For rpm/deb installations the location is typically in /etc/elasticsearch

    if the file is placed in the wrong location Buckler does not enforce any permissions, so your instance/cluster is not secure.

  3. Enable Buckler: at this point there are no configuration properties within buckler.yml, so the features of the Buckler plugin are disabled. 


    To enable the Buckler for basic HTTP authentication, you add these properties to the file, creating a username and password that Bitbucket will use to access Elasticsearch (configured in a later step).

    elasticsearch/config/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...
    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...
    ParameterValueDescription
    auth.basic.http.enabled:
    
    true
    Enables basic authentication for HTTP.
    auth.basic.tcp.enabled:
    true
    Enables basic authentication for TCP.
    auth.basic.username:
    <username>
    Username to access Elasticsearch instance.
    auth.basic.password:
    <password>
    Password to access Elasticsearch instance.
    tls.http.enabled:
    true
    Enables TLS for HTTP.
    tls.tcp.enabled:
    true
    Enables TLS for TCP.
    tls.keystore.path:
    <path/to/keystore>
    Absolute filesystem path to the keystore.
    tls.keystore.password:
    <keystorepassword>
    Password for accessing the keystore.

    If you enable TLS, the following block will need to be added to elasticsearch.yml

    http.type: buckler
    transport.type: buckler


    This is relevant for Buckler version 1.0.1 onwards.

  4. Start your remote Elasticsearch instance. See Elasticsearch (6.8.6) documentation for specific instructions.

Step 4: Connect Elasticsearch to Bitbucket

Once you've configured your Elasticsearch instance you then need to connect it to Bitbucket. 

To configure your remote Elasticsearch instance using the bitbucket.properties file

Once a parameter is set in the bitbucket.properties 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 bitbucket.properties file.
  1. Locate the bitbucket.properties file in the <Bitbucket home directory>/shared directory. 
  2. Add the details of your Elasticsearch instance (created in step 3.3 above):

    <Bitbucket home directory>/shared/bitbucket.properties
    plugin.search.elasticsearch.baseurl=http://localhost:9200/
    plugin.search.elasticsearch.username=<username>
    plugin.search.elasticsearch.password=<password>
  3. Save and close the file.
  4. Start Bitbucket Server without starting the bundled Elasticsearch instance.

    For Linuxstart-bitbucket.sh --no-search 
    For Windowsstart-bitbucket.bat /no-search

Your remote Elasticsearch instance is now configured to work with Bitbucket Server.

Last modified on May 9, 2022

Was this helpful?

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