Install and configure a remote Elasticsearch instance

Install Elasticsearch on a remote machine

We don't provide specific instructions for installing Elasticsearch, but a good place to start is the Elasticsearch installation instructions. Elastic provides installation packages in several different formats on their downloads page.

Note that the authentication plugin – Buckler, described within the Secure your remote Elasticsearch instance section – only supports version 2.3 of Elasticsearch. Refer to the Supported Platforms - Additional Tools page to see the current Elasticsearch release we support.

Configure your remote Elasticsearch instance

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

To configure your remote Elasticsearch instance to be compatible with Bitbucket Server

1. Locate the elasticsearch.yml file within the configuration path of your Elasticsearch instance. 

2. Add these parameters to your elasticsearch.yml file
   

   Parameter	Value
   index.mapper.dynamic	false
   action.auto_create_index	false
   network.host	0.0.0.0

   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.

Secure your remote Elasticsearch instance

After you've completed installing Bitbucket Server, you need to secure access to your remote Elasticsearch instance with a username and password. Atlassian recommends 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

1. Download the Buckler plugin on the remote machine:

   Elasticsearch 2.3.1	Buckler 0.2.11 for ES 2.3.1
   Elasticsearch 2.3.2	Buckler 0.2.11 for ES 2.3.2
   Elasticsearch 2.3.3	Buckler 0.2.11 for ES 2.3.3
   Elasticsearch 2.3.4	Buckler 0.2.11 for ES 2.3.4

2. Install the plugin onto your remote Elasticsearch instance using the plugin helper in the Elasticsearch /bin directory:

   cd /path/to/elasticsearch/bin
   ./plugin install -b <link from table above>

3. Configure basic authentication (at minimum) using the Buckler authentication plugin. 

   1. Within the elasticsearch/config directory, create a directory called buckler.
   2. Create a file named buckler.yml. By default there is no configuration, which means all the features of the Buckler plugin are disabled.

   3. Enable basic authentication by adding the following properties, modifying the parameters for your company's details.

      Here's an explanation of all the parameters you can configure...

      Parameter	Value	Description
      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.

      Here's an example config which enables HTTP authentication...

      auth.basic.http.enabled: true
      auth.basic.username: admin
      auth.basic.password: basicpassword

      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

Connect your Elasticsearch instance to Bitbucket Server

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

To connect your remote Elasticsearch instance to Bitbucket Server via the bitbucket.properties file

Another way to configure connection settings is via bitbucket.properties file (resides in $BITBUCKET_HOME/shared).

1. In the $BITBUCKET_HOME directory, create a new directory called shared.
2. In the $BITBUCKET_HOME/shared directory, create a text file named bitbucket.properties.

3. Add these Elasticsearch properties to the file.

   Property	Parameter name for properties file
   URL	plugin.search.elasticsearch.baseurl
   Username	plugin.search.elasticsearch.username
   Password	plugin.search.elasticsearch.password

   Here's a configuration example...

   plugin.search.elasticsearch.baseurl=http://localhost:9200/
   plugin.search.elasticsearch.username=username
   plugin.search.elasticsearch.password=password

4. Save and close the file.

5. Start Bitbucket Server.

Configure details of your Elasticsearch instance within Bitbucket Server

To configure the details of your Elasticsearch instance within the Bitbucket Server UI, go to the Administration settings page, then click Server Settings. At the bottom of the page is where you can configure the details of your Elasticsearch instance.

Migrate from using the bundled Elasticsearch instance to using a remote Elasticsearch instance

To begin using a remote instance of Elasticsearch after having previously installed a standard instance of Bitbucket Server, which uses the bundled Elasticsearch instance:

1. Install the remote Elasticsearch instance.
2. Configure the remote Elasticsearch instance to work with Bitbucket Server.
3. Secure the remote Elasticsearch instance.
4. Configure the remote Elasticsearch instance details within Bitbucket Server.

To start Bitbucket Server when using a remote Elasticsearch instance, use start-webapp.sh

Once your remote Elasticsearch instance is installed, configured, and secured, you will start Bitbucket Server by running start-webapp.sh instead of start-bitbucket.sh. This starts Bitbucket Server without running the bundled Elasticsearch instance.