Code search

Helix TeamHub supports using Elasticsearch to search code in repositories. Elasticsearch is not included as part of TeamHub packages. It can be installed in multiple ways depending on your needs: inside a TeamHub instance (only recommended for small instances), as a separate machine, or as a cluster of separate machines. See the official documentation for installing Elasticsearch and for configuring production deployment.

The following Elasticsearch versions are supported:

• TeamHub 2022.2 and later: Elasticsearch 7.x
• TeamHub 2023.4 and later: Elasticsearch 8.x

For information on upgrading from an earlier TeamHub version, see the release notes.

Prerequisites

The first step is to estimate the index size based on the storage size of the repositories that support code search. Using this figure with future growth in mind, you can decide the type of Elasticsearch installation and number of shards to create. See capacity planning for more details.

Configuration

Once you have a running instance of Elasticsearch, you can configure TeamHub to use it.

Standard

Append the following minimum configuration to /var/opt/hth/shared/hth.json and make sure to add the settings under the existing backend key.

{
  "backend": {
    "search_engine": "elasticsearch",
    "es_hosts": [
        {
            "host": "your.elastic.host",
            "port": 9200
        }
    ]
  }
}

See backend section in configuration flags for additional settings:

{
  "backend": {
    "search_engine": "elasticsearch",
    "es_index_prefix": "optional",
    "es_number_of_shards": 5,
    "es_number_of_replicas": 1,
    "es_hosts": [
        {
            "host": "your.elastic.host",
            "port": 9200,
            "user": "username",
            "password": "password",
            "scheme": "https"
        }
    ]
  }
}

Apply the changes by reconfiguring TeamHub:

sudo hth-ctl reconfigure

Create the Elasticsearch index as a hth user. Make sure to load a new session for hth user after running reconfigure:

sudo su - hth
cd /opt/hth/application/backend/current/
bundle exec rake hth:search:create_index

Enterprise and HA

Follow the same steps as in Standard section above in one of the web nodes. After creating the index, reconfigure rest of the web nodes before enabling search in TeamHub Client.

sudo hth-ctl reconfigure

Enabling search

After configuration, you can enable the search inside a company, as follows:

1. Log in to the TeamHub client as a company admin.

2. To access the company settings, do one of the following:

   • In the My Dashboard view, click the gear icon next to the company name.
   • In any view, click the user name in the site header and select Company settings.
3. In the Company settings form, on the Features tab, enable Code Search.
4. Save your settings.
5. Wait for the indexing to complete. The initial indexing can take a long time, depending on the size of the repositories. You can see the indexing status in the company overview.

For information on other features that company admins can configure, see Feature settings.

Index management

After changing index configurations later on, such as number shards, the index can be recreated as a hth user. Make sure to load a new session for hth user after running reconfigure:

sudo su - hth
cd /opt/hth/application/backend/current/

Create, delete, or recreate the index:

bundle exec rake hth:search:create_index

bundle exec rake hth:search:delete_index

bundle exec rake hth:search:recreate_index

Refresh all repositories for a company (by short_name) since last indexing, or perform full reindexing (can take a long time):

bundle exec rake hth:search:reindex_company[company]

bundle exec rake hth:search:reindex_company[company,full]

Refresh all repositories for all companies since last indexing, or perform full reindexing (can take a long time):

bundle exec rake hth:search:reindex_instance
 
bundle exec rake hth:search:reindex_instance[full]

Refresh a repository (by short_names) since last indexing, or perform full reindexing:

bundle exec rake hth:search:reindex_repository[company,project,repository]

bundle exec rake hth:search:reindex_repository[company,project,repository,full]