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.
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
elasticsearch.yml file contains configuration details for your Elasticsearch instance.
To configure your remote Elasticsearch instance to be compatible with Bitbucket Server
- Locate the
elasticsearch.ymlfile within the configuration path of your Elasticsearch instance.
Add these parameters to your
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
Download the Buckler plugin on the remote machine:
Install the plugin onto your remote Elasticsearch instance using the plugin helper in the Elasticsearch
cd /path/to/elasticsearch/bin ./plugin install -b <link from table above>
Configure basic authentication (at minimum) using the Buckler authentication plugin.
- Within the
elasticsearch/configdirectory, create a directory called
- Create a file named
buckler.yml. By default there is no configuration, which means all the features of the Buckler plugin are disabled.
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
Enables basic authentication for HTTP.
Enables basic authentication for TCP.
Username to access Elasticsearch instance.
Password to access Elasticsearch instance.
Enables TLS for HTTP.
Enables TLS for TCP.
Absolute filesystem path to the keystore.
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: basicpasswordHere'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
- Within the
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
Another way to configure connection settings is via
bitbucket.properties file (resides in
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
- In the
$BITBUCKET_HOMEdirectory, create a new directory called
- In the
$BITBUCKET_HOME/shareddirectory, create a text file named
Add these Elasticsearch properties to the file.PropertyParameter name for properties file
plugin.search.elasticsearch.passwordHere's a configuration example...
plugin.search.elasticsearch.baseurl=http://localhost:9200/ plugin.search.elasticsearch.username=username plugin.search.elasticsearch.password=password
Save and close the file.
- 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
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:
- Install the remote Elasticsearch instance.
- Configure the remote Elasticsearch instance to work with Bitbucket Server.
- Secure the remote Elasticsearch instance.
- Configure the remote Elasticsearch instance details within Bitbucket Server.
To start Bitbucket Server when using a remote Elasticsearch instance, use
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.