Search (Solr) for your site

Want fast, faceted, typo-tolerant search on your Drupal site? BOA gives each of your sites its very own Solr search core, and setting it up is refreshingly hands-off. You add three lines to one settings file, wait a few minutes, and BOA builds the core for you and hands back the connection details. No server access, no tickets for the routine cases — you drive the whole thing from your site's settings file and your Drupal admin.

This page walks you through it end to end: turning search on, wiring up the Drupal module, cloning and moving sites that already have search, and cleaning up a core you no longer need.

First, is search available?

Solr has to be installed on the server before any of this works — and that part belongs to your host, not to you. If you follow the steps below and no core ever appears (no solr.php file after ten minutes or so), search probably isn't enabled on your server yet. That's a one-line request: open a support ticket and ask your host to enable Solr. Once it's on, everything below is yours to do.

Two things worth knowing up front:

• Search cores are per site, not per platform. You turn search on for each individual site, in that site's own settings — there's no platform-wide switch.
• Solr 9 is available on BOA PRO servers. If you're not sure which your host runs, ask; the setup steps are the same either way, only the version differs.

The one file you edit

Everything you switch on lives in your site's boa_site_control.ini file. You'll find it in your site's modules folder, reachable over SFTP or from your own shell:

sites/yoursite.com/modules/boa_site_control.ini

If you've tuned other per-site settings before, this is the same file. It ships full of commented-out examples — lines that start with ; are switched off. You turn a setting on by removing the leading ; and giving it a value. (For a fuller tour of this file and how BOA picks it up, see Platform and site INI settings.)

There are three search settings you can use:

• solr_integration_module — turns search on and picks the core type.
• solr_update_config — whether BOA refreshes the core's config on module upgrades.
• solr_custom_config — whether you're supplying your own config files.

Turning search on

The only setting you strictly need is the first one. Uncomment it and set it to match the Drupal module you're using:

solr_integration_module = search_api_solr9

That's the switch. The value tells BOA which kind of core to build:

Pick the one that matches the search module in your codebase (more on that in the next section). Save the file, and you're done on the settings side.

One hard rule to get right: search_api_solr9 only builds a core on Drupal 10.2+ or Drupal 11. If you set it on Drupal 8 or 9, BOA builds nothing and no solr.php ever appears. On D8/D9 use search_api_solr7 (or search_api_solr) for a Solr 7 core instead.

Then wait a few minutes. BOA runs a small helper every 5–10 minutes that notices your new setting and builds the core for you — you don't have to trigger anything or wait until overnight. When it's finished, a new file appears in your site directory: solr.php. That file appearing is your signal that the core is ready.

Adding the Drupal module

Turning on solr_integration_module builds the Solr side — the empty search core on the server. It does not touch your Drupal codebase. You still need the matching search module in your site, exactly as you'd install any contributed module:

Add and enable it the usual way for your codebase:

• Composer-managed (modern Drupal): composer require drupal/search_api_solr, then enable it in your Drupal admin.
• Drush-managed Drupal 7: download it into sites/all/modules/contrib/ and run drush en search_api_solr from your shell.

The idea to hold onto: BOA makes the core, you add the module. Neither half works without the other.

Connecting Drupal to your core: solr.php

Once the core is ready, BOA writes the connection details into solr.php in your site directory:

sites/yoursite.com/solr.php

Open it (over SFTP or in your shell) and you'll see the values Drupal needs — the Solr host, the port, the core name, and the path. Something like:

Your SOLR core access details for yoursite.com site are as follows:

  Solr host ........: 127.0.0.1
  Solr port ........: 9099
  Solr path ........: leave empty
  Solr core ........: <your-core-name>

Copy those into the search server configuration in your Drupal admin (the Search API server settings). That's what actually points your site at its core.

One thing to keep in mind: solr.php is just a note to you. Drupal doesn't read it and it isn't part of your site's runtime config — it's BOA's way of handing you the credentials so you can type them into the Drupal UI. It's also read-only by design, so don't try to edit it; if the details ever change, BOA rewrites it for you.

Generating your own config files (modern Drupal)

On modern Drupal (D8+), the search_api_solr module can generate schema.xml and solrconfig.xml files tuned to your site's fields. If you want BOA's core to use those instead of the module's defaults:

1. In your Drupal admin, configure Search API / search_api_solr and download the generated config files.

2. Upload them into your site's Solr config folder over SFTP:

   sites/yoursite.com/files/solr/

3. Make sure solr_custom_config = NO (or leave it commented out) so BOA's auto-installer picks the files up on its next pass.

Within 5–10 minutes BOA activates your uploaded config on the core. If nothing seems to change, double-check that solr_custom_config is not set to YES — that's the setting that tells BOA to leave the config alone.

The two optional settings

You don't need these to get search working — reach for them only when you have a reason.

solr_update_config

solr_update_config = NO

When your search module ships a new release, its bundled schema.xml and solrconfig.xml may change. Left at NO, BOA keeps your core's current config untouched across those upgrades — safe and predictable. Set it to YES if you want BOA to refresh the core's config automatically whenever the module updates. (This setting is ignored when solr_custom_config = YES.)

solr_custom_config

solr_custom_config = NO

Set this to YES to lock your core's config files so BOA never overwrites them — useful when you've hand-tuned schema.xml/solrconfig.xml and want them to stay put across upgrades.

Two caveats:

• While it's YES, the "upload generated config to files/solr/" workflow above won't take effect — that's the trade-off for making the config immutable. If you need to push a fresh config, flip it back to NO briefly (5–10 minutes) so the change lands, then set it to YES again.
• On a hosted BOA service you can't drop custom config files onto the server yourself. If you need your own schema.xml/solrconfig.xml installed with this option on, that's a support ticket to your host — send them the files and ask to have them applied.

Cloning a site that has search

When you clone a site that already has a Solr core, the clone gets its own brand-new core within a few minutes — it doesn't share the original's. That means:

• A fresh solr.php appears on the clone, with its own unique credentials. Update the clone's Drupal search settings to use those new values.
• The clone's index starts empty — it isn't a copy of the original's index. You'll re-index the clone once you point it at its own core.
• Cron is left disabled on the clone by default, so an automatic re-index doesn't fire the moment it's created. Enable cron on the clone when you're ready to build its index.

Moving a site that has search

Solr cores travel with the site, not the platform — so a site with search can be moved between platforms safely. When you migrate a site:

• Its solr_integration_module setting comes along, so search stays configured.
• Its solr.php credentials are preserved — no need to re-wire Drupal.
• The core and its index stay attached; there's nothing to re-index just because you moved platforms.

Run Verify on the site after the move (as you would after any migration) and you're set. You can also upgrade the search module in your codebase over time, as long as the newer version stays compatible with the schema.xml/solrconfig.xml your core is running.

Turning search off

To remove a core you no longer need, just comment its line back out:

;solr_integration_module = search_api_solr9

Within about 15 minutes BOA cleanly deletes the core. The Drupal module stays in your codebase — disable or remove it in Drupal yourself if you're finished with it.

A common Drupal 7 hiccup

If you're on Drupal 7 using apachesolr_attachments to index file contents, you may see this in your logs:

Apache Solr Attachments Java executable not found;
Could not execute a java command.

It just means the module needs to be told where Java lives. Add this line to your site's local.settings.php:

$conf['apachesolr_attachments_java'] = '/usr/bin/java11 -Xms32m -Xmx64m';

(The path is java11 because that's the Java your server provides.) Save, and the attachment indexing will find Java on its next run.

Where to go next

• The settings file you edited here — and everything else you're allowed to tune per site — is covered in Platform and site INI settings.
• Cloning and moving sites in general (search or no search) lives in Cloning and moving a site.
• Every control-file setting name is collected in the shared Reference.