Administer code search
Bitbucket Data Center and 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). Learn more about Bitbucket search syntax.
This page explains how Bitbucket Server and 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.
A search server 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. A Bitbucket Data Center installation requires a remote shared search server.
Important details and requirements about Bitbucket and a search server
This section outlines important considerations for using Bitbucket and a search server. Read the section appropriate for your installation.
For all Bitbucket Server/Data Center installations
- A search server is required to run Bitbucket Server and 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.
For Bitbucket Server installed using the installer or an archive file (.zip/.tar.gz)
- If you install Bitbucket Server using the installer or an archive file (.zip/.tar.gz), a bundled search server is configured to work out of the box.
- Bitbucket Sever's bundled search server requires ports 7992 and 7993 to be available. This is not configurable when using the bundled search server. If these ports are not available, you will need to configure a remote Elasticsearch server or remote OpenSearch server to work with Bitbucket.
For Bitbucket Data Center installations
- Bitbucket Data Center requires a remote search server, as it is not bundled or installed for Bitbucket Data Center. You must install and configure a remote search server, as described in the installation instructions for Bitbucket Data Center.
- However if your organization doesn't need high availability or disaster recovery capabilities right now, you can install Bitbucket Data Center without setting up a cluster. This allows you to use the search server bundled with Bitbucket Server. To do this, follow the installation process for a Bitbucket Server installation, just be sure to enter your Data Center license.
- Bitbucket Data Center 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 cannot guarantee support for such a setup the in event you encounter problems.
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:
- Configure the details of your search server within the Bitbucket Server UI, or
- Configure the details of your search server within the
bitbucket.propertiesfile.
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.
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.
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. It is also possible for Bitbucket Server to connect to an external search server. This may be a standalone search server installation or a clustered installation behind a load balancer.
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 Data Center with a remote search server
To start Bitbucket when using a remote search server
| Bitbucket Data Center | Bitbucket Data Center does not install the bundled search server, so will always start without it. |
|---|---|
| Bitbucket Server on Linux (not a service) | start-bitbucket.sh /no-search
|
| Bitbucket Server on Linux (as a service) | Modify your start service script to pass --no-search to start-bitbucket.sh. |
| Bitbucket Server on Windows (not a service) | start-bitbucket.bat --no-search |
| Bitbucket Server on Windows (as a service) | Do not start the bundled search service. |
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 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 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 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 Datacenter 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 Server/Data Center?
Yes. A search server is required to run Bitbucket Server and Data Center (although code search can be disabled entirely if needed).
Can I use the bundled search server with Bitbucket Data Center?
No. Bitbucket Data Center requires a remote search server, as it is not bundled or installed for Bitbucket Data Center.
If you're installing Data Center on a single node, you can choose a Standard installation type instead, because this type comes with a bundled search server and is suitable for a non-clustered Data Center deployment. In the Data Center installation type, you would need to install it separately.
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.