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.
On this page
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
- Locate the
elasticsearch.ymlfile within the configuration directory of your Elasticsearch server. Add these properties to your
elasticsearch.ymlfile:elasticsearch.ymlaction.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 foraction.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.17.16 | Buckler 3.2.0 |
| Elasticsearch 7.17.10 | Buckler 3.1.1 |
Elasticsearch 7.17.6 | Buckler 3.1.0 |
| 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 /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.
- Create a directory called buckler within the Elasticsearch configuration directory.
Within the <E
lasticsearch config>/bucklerdirectory, create a file namedbuckler.yml.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.ymlauth.basic.http.enabled: true auth.basic.username: <username> auth.basic.password: <password>4. To configure Elasticsearch to use Buckler for security, the following properties need to be added to
elasticsearch.yml:elasticsearch.ymlhttp.type: buckler transport.type: buckler5. 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 bitbucket.properties file.
To configure your remote Elasticsearch server using the bitbucket.properties file:
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 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.propertiesplugin.search.config.baseurl=<search server URL> #e.g. http://localhost:9200/ plugin.search.config.username=<username> plugin.search.config.password=<passwordStart (or restart) Bitbucket without starting the bundled search server.
Bitbucket Data Center clustered Bitbucket Data Center clustered does not install the bundled search server, so will always start without it. Bitbucket Data Center single node (not a service) start-bitbucket.sh --no-searchBitbucket Data Center single node (as a service) Modify your start service script to pass --no-searchtostart-bitbucket.sh.Your remote Elasticsearch server is now configured to work with Bitbucket.