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
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
rpm package) the the configuration directory is typically
To configure your remote Elasticsearch server
- Locate the
elasticsearch.ymlfile within the configuration directory of your Elasticsearch server.
Add these properties to your
action.auto_create_index: ".watches,.triggered_watches,.watcher-history-*" xpack.security.enabled: falseThird 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 version||Buckler plugin|
|Elasticsearch 7.16.3||Buckler 3.0.1|
|Elasticsearch 7.16.2||Buckler 3.0.0|
|Elasticsearch 7.10.2||Buckler 2.1.5|
Buckler can then be installed into your remote Elasticsearch server using the plugin helper in the Elasticsearch
./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.
- Create a directory called buckler within the Elasticsearch configuration directory.
Within the <E
lasticsearch config>/bucklerdirectory, create a file named
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: keystorepasswordHere's an explanation of all the parameters you can configure...
Parameter Value Description
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
http.type: buckler transport.type: buckler
5. Start your remote Elasticsearch server.
Step 4: Connect Elasticsearch to Bitbucket
Once you've configured your remote Elasticsearch server, you then need to connect it to Bitbucket.
To configure your remote Elasticsearch server using the
bitbucket.propertiesfile, 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.propertiesfile and require a restart of Bitbucket to be applied.
- Locate the
bitbucket.propertiesfile in the
<Bitbucket home directory>/shareddirectory.
Add the details of your Elasticsearch server (created in step 3.3 above):<Bitbucket home directory>/shared/bitbucket.properties
plugin.search.config.baseurl=<search server URL> #e.g. http://localhost:9200/ plugin.search.config.username=<username> plugin.search.config.password=<password
Start Bitbucket without starting the bundled search server.
Bitbucket Data Center Bitbucket Data Center does not install the bundled search server, so will always start without it. Bitbucket Server on Linux (not a service)
Bitbucket Server on Linux (as a service) Modify your start service script to pass
Bitbucket Server on Windows (not a service)
Bitbucket Server on Windows (as a service) Do not start the bundled search service.
Your remote Elasticsearch server is now configured to work with Bitbucket.