Cloud
Data Center 4.7
Versions

Install and configure a remote Elasticsearch instance

Advanced actions

On this page

Related content

Still need help?

The Atlassian Community is here for you.

Ask the community

Bitbucket Server 4.6+ comes with an bundled Elasticsearch instance, which runs as a separate process from the Bitbucket Server application and doesn't require any extra configuration. You can can also install a remote Elasticsearch instance on a remote machine, which can provide some advantages allocating memory resources.

For the most part, you would be better off using our bundled Elasticsearch that will be automatically configured with its scripts out of the box. However, if you have a Bitbucket Data Center instance, for example, it is a requirement that you have only one single remote Elasticsearch instance for your cluster as described on Installing Bitbucket Data Center. 

It could also be that despite of you having one single instance you still want to use your own Elasticsearch for your own reasons in which case this guide is also helpful. In this case, we strongly suggest that you use our bundled version, though.

This page describes

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.

Elasticsearch ports

Bitbucket Server's bundled Elasticsearch instance requires ports 7992 and 7993 be available to provide code search functionality. This is not configurable, so ensure these ports are available.

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

    ParameterValue
    index.mapper.dynamicfalse
    action.auto_create_indexfalse
    network.host0.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.1Buckler 0.2.11 for ES 2.3.1
    Elasticsearch 2.3.2Buckler 0.2.11 for ES 2.3.2
    Elasticsearch 2.3.3Buckler 0.2.11 for ES 2.3.3
    Elasticsearch 2.3.4Buckler 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...
      ParameterValueDescription
      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).

If a parameter is set in the 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.

  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
    URLplugin.search.elasticsearch.baseurl
    Usernameplugin.search.elasticsearch.username
    Passwordplugin.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.

If a parameter is set in the 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.

 

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.

Last modified on Jul 15, 2016

Was this helpful?

Yes
No
Provide feedback about this article

Related content

Powered by Confluence and Scroll Viewport.