Overview

The way that external fulltext search engines are configured has changed in 2017 Week 13.

• If you use MySQL search, you are not impacted by the configuration changes and do not need to take any action. The vast majority of installs use MySQL search, and MySQL search is recommended in most cases.
• If you use Elasticsearch, configuration has changed. Version compatibility may also have changed. See below for details.

For all installs, see Optional Project/Repository Indexes below for some optional steps.

Elasticsearch: Configuration Changes

The way Elasticsearch is configured has changed. These configuration options have been removed:

• search.elastic.host - Now configured with cluster.search.
• search.elastic.namespace - Now configured with the "path" key in cluster.search. See the next section for discussion.

If you currently use Elasticsearch with a setting like http://elastic.example.com:9200/ for search.elastic.host, your new cluster.search setting should be:

[
  {
    "type": "elasticsearch",
    "hosts": [
      {
        "protocol": "http"
        "host": "elastic.example.com",
        "port": 9200
      }
    ]
  }
]

For more details, see Cluster: Search.

Elasticsearch: Paths

If you previously used search.elastic.namespace, set the value as "path", as a top-level key in the service definition:

[
  {
    "type": "elasticsearch",
    "path": "/phabricator2",
    "hosts": [
      ...
    ]
  }
]

Use of this option is very rare.

Elasticsearch: Versions

Phabricator has historically had uneven support for different versions of Elasticsearch. The updated code has primarily been developed and tested against Elasticsearch 5 (the most recent version, at time of writing) and will work best with a modern Elasticsearch server.

If you run Elasticsearch 2, you can add "version" as a top-level key in the service definition:

[
  {
    "type": "elasticsearch",
    "version": 2
    "hosts": [
      ...
    ]
  }
]

This is also supported, but has not been tested as thoroughly.

If you run an older version, you may find things don't work; you are probably best off upgrading to Elasticsearch 5. See the next section for guidance.

Elasticsearch: Hard Reset

If you'd like to upgrade to Elasticsearch 5 from an older version of Elasticsearch, or generally wipe the slate clean and start from scratch, do this:

• Set up Elasticsearch 5.
• Configure cluster.search to point at it.
• Run bin/search init.
• Run bin/search index --all --background --force to populate the index.

This last command can be run while Phabricator is online. For general guidance on rebuilding search indexes, see T11932.

Optional Project/Repository Indexes

Adjacent to these configuration changes, some document types now have slightly richer fulltext indexes. You may optionally reindex projects and repositories to take advantage of these updates. If you do, users may have better luck finding relevant project and repository results using global search. This impacts both MySQL and Elasticsearch. If you don't run these commands, the indexes will tend to naturally update over time on their own.

phabricator/ $ ./bin/search index --type project --force
phabricator/ $ ./bin/search index --type repository --force

These commands can be run while Phabricator is running and should complete quickly (a few minutes at most) for most installs.