Administer code search

Administer Bitbucket Data Center

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

Bitbucket Data Center 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). Learn more about Bitbucket search syntax.

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

About search servers

Code search is powered by a search server, which indexes the content of Bitbucket repositories in real time. The search server distributions supported by Bitbucket are Elasticsearch and OpenSearch.

Support for Elasticsearch has been deprecated and will be removed in Bitbucket Data Center 9.0. If you're planning to use an external search server, we recommend using OpenSearch.

A clustered Bitbucket Data Center installation requires an external search server.

Important details and requirements about Bitbucket and a search server

This section outlines important considerations for using Bitbucket and a search server.

  • A search server is required to run Bitbucket Data Center (although code search can be disabled entirely if needed).
  • For information on supported versions of search servers and Bitbucket, please refer to Supported platforms
  • You can configure what is indexed for code search to exclude various types of forked repositories to save disk space.

  • Running a clustered Bitbucket Data Center installation requires a remote search server that you should install and configure.
    • To configure an external OpenSearch server, see Install and configure a remote OpenSearch server. Another option is Amazon OpenSearch Service. To check which search server versions are supported now, see the Supported platforms page.
    • If your organization doesn't need high availability or disaster recovery capabilities now, you can install Bitbucket Data Center without setting up a cluster (that is a single-node installation) and use a bundled search server instead. 
  • A clustered Bitbucket Data Center installation can have only one remote connection to the shared search server for your cluster. This may be a standalone search server 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 search server nodes to achieve high availability, although Atlassian can't guarantee support for such a setup in the event you encounter issues.

Change the username and password for accessing the search server

There are two ways you can change the user credentials Bitbucket uses to access the search server: 

  1. Configure the details of your search server within the Bitbucket UI, or
  2. Configure the details of your search server within the  bitbucket.properties  file.

If a search server 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 search server configuration, must be made within the  bitbucket.properties  file.

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

Go to  > Server settings > Search

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

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

  2. Add the details of your search server.

    <Bitbucket home directory>/shared/bitbucket.properties
    plugin.search.config.baseurl=http://localhost:7992/
    plugin.search.config.username=<username>
    plugin.search.config.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 search server configuration must be made within the bitbucket.properties file and require a restart of Bitbucket to be applied.

Use a remote search server with Bitbucket 

A clustered Bitbucket Data Center installation requires a remote search server, as no search server is bundled or installed for Bitbucket Data Center.

For instructions on setting up a single remote instance of OpenSearch to use with Bitbucket, see Install and configure a remote OpenSearch server .

For instructions on setting up a single remote instance of Elasticsearch to use with Bitbucket, see Install and configure a remote Elasticsearch server.

For guidance on using a clustered search server installation with Bitbucket Data Center, including Amazon OpenSearch Server, see Use a clustered search server with Bitbucket Data Center.

Start Bitbucket with a remote search server

To start Bitbucket when using a remote search server

Bitbucket Data Center clusteredBitbucket Data Center clustered does not install the bundled search server, so will always start without it.
Bitbucket Data Center single node (not a service)start-bitbucket.sh /no-search
Bitbucket Data Center single node (as a service)Modify your start service script to pass --no-search to start-bitbucket.sh.

Troubleshooting and frequently asked questions about the search server

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

Your search server was configured using 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 search server configuration must be made within the bitbucket.properties file.

My remote search server is using up a lot of disk space

You can configure the 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 Configuration properties 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 users, you can disable code search entirely from within the bitbucket.properties file. See the page Configuration properties for details.

Code search is unavailable

There are a few ways the search server may not have been configured properly. To troubleshoot the bundled search server 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 a search server/code search required to run Bitbucket Data Center?

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

Can I use the bundled search server with a clustered Bitbucket Data Center?

No. Clustered Bitbucket Data Center requires a remote search server as each Bitbucket node must connect to the same external search server.

If you're installing Bitbucket Data Center on a single node, you can choose a single-node installation type instead. This type comes with a bundled search server and is suitable for a non-clustered Bitbucket Data Center deployment.

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

Yes, however, Bitbucket Data Center can have only one remote connection to the shared search server for your cluster. This may be a search server installation or a clustered installation behind a load balancer. For guidance on using a clustered search server installation with Bitbucket Data Center, see the page Use a clustered search server with Bitbucket Data Center.

How do I secure my remote search server?

Atlassian strongly recommends you secure access to your remote search server with a username and password, and a minimum of basic HTTP authentication. See Secure your search server for details.

Last modified on Oct 19, 2023

Was this helpful?

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