Install and configure a remote Elasticsearch instance
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 the page Administer code search.
Bitbucket Data Center will only work with Elasticsearch 2.3.5.
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 (2.3) installation instructions. Elastic provides installation packages in several different formats on their downloads page. Note that the authentication plugin – Buckler, described within the Secure Elasticsearch section – only supports versions 2.3 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
- Locate the
elasticsearch.ymlfile within the configuration directory of your Elasticsearch (2.3) instance.
Add these parameters to your
elasticsearch.ymlfileindex.mapper.dynamic: false action.auto_create_index: false network.host: 0.0.0.0Third 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 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 2.3.5 Buckler 0.2.12 for ES 2.3.5 Install the plugin onto your remote Elasticsearch instance using the plugin helper in the Elasticsearch
/bindirectory:cd /path/to/elasticsearch/bin ./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.
- Create a directory called
bucklerwithin theelasticsearch/configdirectory. Within the
elasticsearch/configdirectory, create a file namedbuckler.yml.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.ymlauth.basic.http.enabled: true auth.basic.username: <username> auth.basic.password: <password>- Start your remote Elasticsearch instance. See Elasticsearch (2.3) documentation for specific instructions.
- Create a directory called
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
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.
- Locate the
bitbucket.propertiesfile in the<Bitbucket home directory>/shareddirectory. Add the details of your Elasticsearch instance (created in step 3.3 above):
<Bitbucket home directory>/shared/bitbucket.propertiesplugin.search.elasticsearch.baseurl=http://localhost:9200/ plugin.search.elasticsearch.username=<username> plugin.search.elasticsearch.password=<password>- Save and close the file.
Start Bitbucket Server without starting the bundled Elasticsearch instance.
For Linux start-bitbucket.sh --no-searchFor Windows start-bitbucket.bat /no-search
Your remote Elasticsearch instance is now configured to work with Bitbucket Server.