Install and configure a remote OpenSearch server
This page describes how to provision a remote OpenSearch server to work with Bitbucket Data Center.
Bitbucket Data Center requires a remote search server, as no search server is bundled or installed for Bitbucket Data Center. OpenSearch is a supported search server distribution for Bitbucket Data Center.
Bitbucket Data Center can have only one remote connection to OpenSearch for your cluster. This may be a standalone OpenSearch installation or a clustered installation behind a load balancer.
For details on how Bitbucket uses the search server, including troubleshooting tips and frequently asked questions, see Administer code search.
Step 1: Install OpenSearch on a remote machine
We don't provide specific instructions for installing OpenSearch, but a good place to start is the OpenSearch guide for installation.
Step 2: Configure OpenSearch
opensearch.yml file contains configuration details for your OpenSearch server.
The location of your OpenSearch configuration directory varies depending on how you installed OpenSearch. For installations from an archive the configuration is
To configure your remote OpenSearch server
opensearch.ymlfile within the configuration directory of your OpenSearch server.
Add these properties to your opensearch.yml file:
Step 3: Secure OpenSearch
Bitbucket communicates to OpenSearch over HTTP using the OpenSearch REST API and can be configured to use basic authentication (a username and password). The OpenSearch provided security plugin can be configured for this purpose.
The minimal distribution of OpenSearch does not contain the OpenSearch security plugin. A custom security solution is required to use the minimal OpenSearch distribution with Bitbucket.
The instructions below describe a simple way to configure the OpenSearch security plugin for the minimum requirements that Bitbucket needs to connect to OpenSearch securely. This is useful if you are migrating from using Elasticsearch with Buckler and want the search server security configuration to work in a similar way, or just want a basic configuration to begin with.
The OpenSearch security plugin also supports many additional features and methods of configuration, which are documented in the OpenSearch security plugin documentation.
Follow the instructions below to secure your remote OpenSearch server with the OpenSearch security plugin. This will involve configuring the OpenSearch security plugin to include a single user in its internal users database called
bitbucket with a selected hashed password which has access to the entire search cluster, and a single authentication domain providing basic authentication against the internal users database.
Transport layer TLS
Transport layer TLS is mandatory to use the OpenSearch security plugin (and optionally TLS can also be applied at the REST layer). See the OpenSearch security plugin Configure TLS certificates documentation on how TLS can be configured. Self-signed certificates can be used (provided the
plugins.security.ssl.transport.enforce_hostname_verification: false property is set in
opensearch.yml) and can be generated using a tool like OpenSSL. Place the generated certificates or keystore/truststore files in the
Replace the configuration files in
$OPENSEARCH_HOME/plugins/opensearch-security/securityconfig/ with the following:
# enable/disable audit logging
description: "Authenticate via HTTP Basic against internal users database"
hash: "##REPLACE WITH HASHED PASSWORD##"
description: "Admin user"
description: "Maps admin to all_access"
The important files are
config.yml: defines a single authenticator, which is using basic authentication on both HTTP and transport, backed by the internal user database
internal_users.yml: creates a single user with username bitbucket (and a provided hashed password, see Generate a password step below), and this user is assigned the admin back-end role
roles_mapping.yml: assigns the admin backend role (that the bitbucket user has) the all_access role, which is a pre-defined role by the OpenSearch security plugin that gives access to the entire search server
d. The remaining files are empty placeholders that the OpenSearch security plugin requires.
Generate a password
Generate a hashed password for the
bitbucket user using the OpenSearch provided hashing tool
$OPENSEARCH_HOME/plugins/opensearch-security/tools/hash.sh. Copy the hashed password into
internal_users.yml, replacing the password placeholder.
This password is what Bitbucket will use to connect to OpenSearch.
To configure OpenSearch security the following properties also need to be added to
#This property causes the OpenSearch security plugin to configure itself based on
#the security configuration yml files if no security configuration exists in on the
#search server yet (e.g. on first start).
#The REST API is locked down by default, even to the 'all_access' roll, so enable
#the 'all_access' role to be able to use it here.
#Transport layer TLS is mandatory. The certificates need to be manually added to the
#OpenSearch config folder. The example settings below are for X.509 certificates and
#PKCD #8 keys, but a keystore and truststore approach can also be used. Refer to the
#OpenSearch security plugin documentation for more information.
#If the generated certificates are self-signed then hostname verification must be
Start your remote OpenSearch server.
plugins.security.allow_default_init_securityindex: true, changing the configuration files in
$OPENSEARCH_HOME/plugins/opensearch-security/securityconfig/ after the first startup of OpenSearch will not have any effect, as the files are only used automatically for the default initialisation of the security index.
Step 4: Connect OpenSearch to Bitbucket
Once you've configured your OpenSearch server, you then need to connect it to Bitbucket.
To configure your remote OpenSearch server using the
bitbucket.properties file, it cannot be edited later from the admin UI. Any changes that need to be made to the OpenSearch configuration, must be made within the
bitbucket.properties file and require a restart of Bitbucket to be applied.
- Locate the
bitbucket.propertiesfile in the
<Bitbucket home directory>/shareddirectory.
Add the details of your OpenSearch server:<Bitbucket home directory>/shared/bitbucket.properties
plugin.search.config.baseurl=<search server URL> #e.g. http://localhost:9200/ plugin.search.config.username=<username> #e.g. bitbucket plugin.search.config.password=<password> #e.g. the password that was hashed
Start Bitbucket without starting the bundled 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)
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)
Bitbucket Server on Windows (as a service)
Do not start the bundled search service
Your remote OpenSearch server is now configured to work with Bitbucket.