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 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 Cloud Platform user interface, 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:
Log in to your Drupal site as an administrator.
Navigate to Admin > Configuration > Search > Search API, and click the server you are editing.
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.
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 custom Solr 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.
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 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 upload your file in the Cloud Platform user interface.
If you receive an error message while uploading the file, see Custom configuration file error messages.
Once uploaded, your custom Solr configset can be applied to any new or existing 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.
Navigate to the desired Cloud Platform environment in the Cloud Platform user interface.
In the left navigation pane, select Search.
Select the database for which you want to create an index.
In the Configuration Set section, select Upload custom configset.
Drag and drop the configset zip file to the drop zone. Acquia Search may take a few minutes to validate the zip file.
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:
Navigate to the desired Cloud Platform environment in the Cloud Platform user interface.
In the left navigation pane, select Search.
Find the index to which you want to apply the custom configset, and select Change configset.
In the Change Configset dialog box, in the Configuration Set section, select Upload custom configset.
Drag and drop the configset zip file to the drop zone. Acquia Search may take a few minutes to validate the zip file.
After the validation is complete, click Submit to apply the configset to the index.
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.
Managing configsets
Uploading a configset
To upload a configset:
Navigate to the desired Cloud Platform environment in the Cloud Platform user interface.
In the left navigation pane, select Search.
On the Configsets tab, click Add configset.
In the Add configset dialog box, click SELECT FILE, select the file to upload, and click OK.
Note
If the upload is successful, the system marks the configset as active. Otherwise, the system displays additional health information.
Deleting a configset
To delete the configset:
Navigate to the desired Cloud Platform environment in the Cloud Platform user interface.
In the left navigation pane, select Search.
On the Configsets tab, click the ellipsis (…) icon for the configset, and click Remove.
In the Remove configset dialog box, click Remove.
The system displays a message to confirm that the configset is deleted.