Information for: DEVELOPERS   PARTNERS

Custom Solr configuration with Solr 7

Acquia Search with Solr 7 allows you to customize your Solr configuration settings, otherwise known in the Solr community as “configsets”, to support more advanced search behavior. Customizing Solr’s configuration settings can give you a high degree of flexibility in controlling how Solr indexes your site content and executes search queries.

You can deploy custom Solr configsets into your Acquia-hosted Solr 7 instances. Example use cases for using a custom configset include:

  • Specifying a list of synonyms and stopwords to Solr.
  • Configuring Solr for various languages.
  • Customizing how indexing and searching works in Solr.

Creating custom configsets typically requires manual editing of XML and TXT Solr configuration files. If you are using the latest version of the Search API Solr module, you can also use the Drupal user interface to edit the settings. You can then use Drupal to generate all the necessary configuration files for you to upload into the Cloud Platform user interface.

Important

Changing your Solr configuration settings without adequate testing can result in broken site search functionality. You are responsible for testing all your Solr configset changes before you upload the configset in the Cloud Platform user interface. For more information, see Testing custom Solr configsets with Solr 7. Acquia cannot help you debug your Solr configuration settings.

Before you begin your custom configset

With Solr 7, you can manage custom Solr configurations through the Acquia Cloud Platform user interface.

Review the following requirements before you begin your custom configset:

  • For the latest Solr version, see Release notes - Acquia Search.
  • Modifications must begin from the default Solr configuration files used with Acquia Search. You can retrieve the configuration files residing on the Solr server through the Acquia Cloud Platform user interface by creating a Solr index for a desired database in the desired environment, and then selecting the Download configset option for that index.
  • Each custom configset that is uploaded must be unique across each Drupal application. You must make at least one change to the downloaded Solr configuration files before they can be re-uploaded to Acquia Search as a unique custom configset.
  • When creating custom configset zip files on macOS, use the zip command. Do not use the Compress command. The Compress command introduces hidden files in the zip file that will result in errors.

Customize your configset

When preparing your custom Solr configset, download the default Acquia Search Solr configset and use it as the starting point for your customization.

  1. Log in to your Drupal site as an administrator.
  2. If you are working with a language other than English, do the following:
    1. Navigate to Configuration > Languages > Add Language.
    2. Configure the Drupal site language.
    3. Set the Language as default.
    4. Save the configuration.
  3. Navigate to Admin > Configuration > Search > Search API and click the server you are editing.
  4. Click the Custom Field Types tab, and add your changes to the relevant field(s).
  5. Click the Get config.zip button to generate the full set of Solr configuration files. This zip file will contain all your necessary Solr configsets, including all your manual changes.
  6. Upload your custom configset to your desired Acquia Cloud Platform environment by completing the following steps.

Note

To deploy Solr 7 configurations, the zip file must contain all the files and not only the files you edited. For information about custom Solr configset file requirements, see Custom Solr configuration with Solr 7. You get all the required files if you download the zip file from the Drupal user interface.

Prepare your configuration files

Test the configset changes that you want to make offline. After testing the changes, create a zip file containing the configuration files. When you upload the configset to your Solr index, Acquia Search validates the format of the zip file and its content to ensure that it meets the following requirements:

  • File type must be zip
  • Total zip file size must not exceed 10 MB
  • The size of each individual file within the zip file must not exceed 5 MB
  • The solrconfig.xml file must exist
  • The schema.xml file must exist
  • The zip file must not contain any folders; all files need to reside at the root of the zip file, without any subfolders.
  • The zip file must only contain files with .xml, .txt, .properties extensions
  • The zip file must contain all files referenced in .xml files
  • Each file in the zip archive must:
    • Be UTF-8 encoded
    • Have no Byte Order Mark
    • Have no CR (Windows-style carriage return) characters
    • Have a valid XML syntax if it is an .xml file

Upload your configuration files

After generating your custom Solr configset zip file, you can apply the configset to a new or existing index.

Applying the configset to a new Solr index

When creating a new index, you can use a previously uploaded custom configset or a brand new configset.

  1. Navigate to the desired environment.
  2. In the left navigation pane, select the Search with Solr 7 option.
  3. Select the database for which you want to create an index.
  4. Choose Upload custom configset under the Configuration Set option.
  5. Drag and drop the configset zip file to the drop zone. Acquia Search may take a few minutes to validate the zip file.
  6. After the validation is complete, click Add to create the index with the new Solr configset.

Applying the configset to an existing Solr index

If you have already created a Solr index:

  1. Navigate to the desired environment.
  2. In the left navigation pane, select the Search with Solr 7 option.
  3. Find the index you want to apply the custom configset to and select Change configset.
  4. In the Change Configset dialog, choose Upload custom configset under the Configuration Set option.
  5. Drag and drop the configset zip file to the drop zone. Acquia Search may take a few minutes to validate the zip file.
  6. After the validation is complete, click Submit to apply the configset to the index.

If you require fine-grained or frequent search configuration customizations, you may want to consider a hosted Apache Solr provider, rather than a software-as-a-service offering like Acquia Search.

Important

Problems in configuration files supplied to Acquia can result in Acquia Search Solr instances to fail to restart after configuration changes, and search will become unavailable to any connected websites or environments.