Information for: DEVELOPERS   PARTNERS   SUPPORT

Custom Solr configuration with Solr 7

Why would I need a custom Solr configuration?

Solr configuration settings, otherwise known as “configsets”, define the data types and behavior available in Solr.

By default, Acquia Search with Solr 7 indexes are configured with an Acquia-provided configset for English-language content. It is based on the out-of-the box settings provided by the Search API Solr Drupal module when installed in a bare-bones Drupal site using the English language.

If your Drupal site shows the message “It is advisable to download and deploy an updated config.zip to your Solr server”, or you need to otherwise tweak the behavior of the Acquia-hosted Solr backend, you must deploy new configuration files into Solr.

The following are some example use cases for using a custom configset:

  • Altering the list of synonyms and stopwords used by Solr.
  • Configuring Solr for various languages.
  • Customizing how indexing and searching works in Solr.

In some cases, the Solr configuration requires following code and configuration changes on your Drupal site. For example, adding a new language to your Drupal site or updating the version of a module could require deploying a new Solr configset that is compatible with these changes. You should review module release notes and be aware of any warning messages shown by Drupal to determine if a configset change is necessary.

For the purposes of this document, a “custom configset” is anything that is not one of the Acquia-provided configsets that can be deployed from the Acquia Cloud UI.

How do I create a Solr configset?

The Search API Solr Drupal module, version 4.x or later, generates Solr configset files based on the Drupal site’s current configuration and code. You can generate a configset using the drush search-api-solr:get-server-config command, or by logging into your Drupal site and clicking the Get config.zip button on the Search API server’s page.

If needed, you can also inspect or download the configset that’s currently deployed in an Acquia Solr index by selecting the Download configset option for that index within the Acquia Cloud UI, or from Drupal by navigating to the Files tab of a Search API server.

Once you have the configset zip file, you can choose to directly deploy it into the Acquia Search Solr index (via the Cloud UI). Additionally, if you have an understanding of Solr, you can use a text editor to edit these files before deployment. Once uploaded, your custom Solr configset can be applied to an index for any environment across your application.

Note that some pieces of configuration such as the synonyms word list, stopwords list, or the protected words list can also be edited directly in the Drupal UI. After any changes, you should re-export the configset zip file and re-deploy it into Solr via the Cloud UI.

For a short video demonstration, see How to use the Drupal UI to edit and generate Solr configuration files

Generate and customize your configuration files

Use the following steps to generate a Solr configset:

  1. Log in to your Drupal site as an administrator.
  2. Navigate to Admin > Configuration > Search > Search API, and click the server you are editing.
  3. If needed, click the Custom Field Types tab and add your changes to the relevant field(s). For example, you can edit the stopwords or synonyms lists here.
  4. Click the Get config.zip button to generate the full set of Solr configuration files. This zip file will contain all your necessary Solr configuration files, including any changes from the previous step.

If needed, you can manually edit any files within this zip. You should not remove or rename any of the files within this zip. Proceed with caution!

Before uploading, rename the zip file to a unique name that you have not used earlier.

Note

If 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.

Note

To deploy Solr 7 configsets, the zip file must contain all the files and not only the files you edited. See the following content for information about Solr configset file requirements. You will have all the required files when generating the zip file via the Drupal user interface.

Test and review your configuration files

Although it is not required, Acquia recommends testing any configset changes on a non-Acquia Solr instance. The reason is that Acquia-hosted Solr neither provides you with detailed logs nor with access to some Solr debugging tools that you may need to use to troubleshoot any custom Solr configuration. Ensure that you are using the same Solr version that Acquia uses. For the latest version, see Release notes - Acquia Search.

Important

Changing your Solr configuration settings without adequate testing might result in broken site search functionality. You are responsible for testing all your Solr configset changes before you upload the configset in the Acquia Cloud Platform user interface. Acquia Support cannot help you debug your Solr configuration settings.

Ensure that you review the configset zip and included files so that they pass the automatic validation that happens during upload. This automated step checks the format of the zip file and its content to ensure that it meets the following requirements:

  • File type must be zip.
  • The zip filename for this Acquia application must be a unique name that has not been used earlier.
  • Overall, the contents of the new configset’s files must be unique across all the configsets you’ve previously uploaded to your application.
  • 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 recommended documentCache value is 128.
  • 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.

Once uploaded, your custom Solr configset can be applied to an index for any environment across your application.

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 Acquia Cloud environment in the Acquia Cloud UI.
  2. In the left navigation pane, select Search with Solr 7.
  3. Select the database for which you want to create an index.
  4. In the Configuration Set section, select Upload custom configset.
  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 Acquia Cloud environment in the Acquia Cloud UI.
  2. In the left navigation pane, select Search with Solr 7.
  3. Find the index to which you want to apply the custom configset, and select Change configset.
  4. In the Change Configset dialog box, in the Configuration Set section, select Upload custom configset.
  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.
  7. After the configset is applied, reindex the data in your Drupal application.

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.