Administer code search

Bitbucket Server allows you to search through your code to find exactly what you’re looking for right from the search bar. You can restrict your search results to a specific project or repository using search filters. You can also search for code in a particular language (e.g., lang:java) or with a particular file extension (e.g., ext:css).

Head to Bitbucket search syntax for details on the search syntax.

This page explains how Bitbucket Server and Data Center uses Elasticsearch, how to configure Elasticsearch to fit the needs of your organization, and provides some tips for troubleshooting common problems.

About Elasticsearch

Code search is powered by Elasticsearch, which indexes the content of Bitbucket Server repositories in real time. Elasticsearch comes bundled with Bitbucket Server and is managed by Bitbucket Server automatically. Under most circumstances it should not need to be managed manually by an administrator.

Important details and requirements about Bitbucket and Elasticsearch

This section outlines important considerations for using Bitbucket and Elasticsearch. Read the section appropriate for your installation.

For all Bitbucket Server/Data Center installations

For Bitbucket Server installed using the installer

  • If you install Bitbucket Server using the installer Elasticsearch is configured to work out of the box.
  • Bitbucket Sever's bundled Elasticsearch instance requires ports 7992 and 7993 to be available. This is not configurable when using the bundles Elasticsearch instance. If these ports are not available, you will need to Install and configure a remote Elasticsearch server to work with Bitbucket.

For Bitbucket Server installed using an archive file (.zip/.tar.gz)

  • After unzipping the archive files, you need to copy the contents of the <Bitbucket installation directory>/elasticsearch/config-template directory to the <Bitbucket home>/shared/search directory, or Bitbucket won't start correctly. Details can be found in the archive installation instructions for Windows and Linux.

For Bitbucket Data Center installations

  • Bitbucket Data Center requires a remote Elasticsearch instance, as it is not bundled or installed for Bitbucket Data Center. You must install and configure a remote Elasticsearch instance, as described in the installation instructions 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. 
  • Code search is not critical for high availability, however it is possible run a cluster of Elasticsearch nodes to achieve high availability, although Atlassian cannot guarantee support for such a setup in event you encounter problems.

Change the username and password for accessing Elasticsearch

There are two ways you can change the user credentials Bitbucket uses to access Elasticsearch. 

  1. Configure the details of your Elasticsearch instance within the Bitbucket Server UI, or
  2. Configure the details of your Elasticsearch instance within the bitbucket.properties file.

If an Elasticsearch parameter is set from within 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.

 

To change the username/password for accessing Elasticsearch from the Bitbucket UI...

Go to  > Server settings > Search

Here you can see the current configuration of Elasticsearch, including the port and user credentials for accessing Elasticsearch. 



To change the username/password for accessing Elasticsearch in the bitbucket.properties file...
  1. Locate the bitbucket.properties file in the <Bitbucket home directory>/shared directory. 

  2. Add the details of your Elasticsearch instance.

    <Bitbucket home directory>/shared/bitbucket.properties
    plugin.search.elasticsearch.baseurl=http://localhost:7992/
    plugin.search.elasticsearch.username=<username>
    plugin.search.elasticsearch.password=<password>

     * <username> and <password> are values you provide.

 

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.

Use a remote Elasticsearch instance with Bitbucket Data Center

Bitbucket Data Center requires a remote Elasticsearch instance, as it is not bundled or installed for Bitbucket Data Center. This may be a standalone Elasticsearch installation or a clustered installation behind a load balancer. 

For instructions on setting up a single remote instance of Elasticsearch to use with Bitbucket Data Center, see the Bitbucket Data Center installation instructions.

For guidance on using a clustered Elasticsearch installation with Bitbucket Data Center, see the page Install and configure a remote Elasticsearch server, but note that Atlassian cannot guarantee support for such a setup in event you encounter problems.

Start Bitbucket Data Center with a remote Elasticsearch instance

Because Bitbucket Data Center requires a remote Elasticsearch instance, you need to start Bitbucket Data Center with an argument that won't try to start the bundled Elasticsearch that comes with Bitbucket Server.

 

To start Bitbucket when using a remote Elasticsearch instance

For Linuxstart-bitbucket.sh --no-search 
For Windowsstart-bitbucket.bat /no-search

Troubleshooting and frequently asked questions about Elasticsearch

I can't configure Elasticsearch settings from the UI because the fields are grayed out

Your Elasticsearch configurations were set within the bitbucket.properties file. 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.

My remote Elasticsearch instance is using up a lot of disk space

With Bitbucket 5.1+ you can configure the Elasticsearch search indexes to exclude certain types of forked repositories, which can save disk space when your company uses a fork-based workflow for development. See the page Bitbucket Server config properties - Search for the options available to change what is indexed for code search. Note that excluding content from being indexed can prevent such content from ever appearing in code search results, but will not prevent the repositories themselves from appearing in search results.

I need to disable code search entirely

If you need to turn off code search for all of your Bitbucket Server (or Data Center) users, you can disable code search entirely from within the bitbucket.properties file. See the page Bitbucket Server config properties - Search for details.

Code search is unavailable

There are a few ways Elasticsearch may not have been configured properly. To troubleshoot the bundled version of Elasticsearch that comes with Bitbucket Server, the page Troubleshooting steps for Bitbucket Server Code Search is a good place to start. If you're still stuck after looking at the tips on that page, you could post a question in the Atlassian Community (in case your configuration is not typical or unsupported), or contact Atlassian Support for assistance (you'll need to log in to raise a support request).

Is Elasticsearch/code search required to run Bitbucket Server/Data Center?

Yes. Elasticsearch is required to run Bitbucket Server and Data Center (although code search can be disabled entirely if needed).

Can I use the bundled instance of Elasticsearch with Bitbucket Data Center?

No. Bitbucket Data Center requires a remote Elasticsearch instance, as it is not bundled or installed for Bitbucket Data Center.

Can I use a clustered installation of Elasticsearch with Bitbucket Data Center?

Yes, however, 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 guidance on using a clustered Elasticsearch installation with Bitbucket Data Center, see the page Install and configure a remote Elasticsearch server, but note that Atlassian cannot guarantee support for such a setup in event you encounter problems.

How do I secure my remote Elasticsearch instance?

Atlassian strongly recommends you secure access to your remote Elasticsearch instance with a username and password, and a minimum of basic HTTP authentication. You can secure 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.

For instructions on how to secure your remote Elasticsearch instance with Buckler, see Install and configure a remote Elasticsearch instance - Secure your remote Elasticsearch instance.

The latest version of Elasticsearch is 5+, but the version supported for use with Bitbucket is 2.3.5. Why is Bitbucket using such an outdated version of Elasticsearch?

Elastic skipped releasing versions 3 and 4 of Elasticsearch. They are not publicly available. While it might seem that Bitbucket is using a version of Elasticsearch that is several versions behind, Elasticsearch 2.3.5 was only released in 2016. This version is more than adequate to provide exceptional functionality to power Bitbucket's code search. If you feel strongly about suggesting Atlassian consider using a different version of Elasticsearch, you can raise a suggestion for improvement with the Bitbucket Server team, or start a discussion in the Atlassian Community. We love to hear from our customers, so if it's important to you, we'd like to hear about it.

Last modified on Sep 21, 2017

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.