Code Search EAP - Install and configure a remote Elasticsearch instance

Install Elasticsearch

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.

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: buckler-plugin-0.1.5.zip.

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 https://maven.atlassian.com/content/groups/public/com/atlassian/elasticsearch/buckler-plugin/0.1.5/buckler-plugin-0.1.5.zip

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.