Last updated January 30, 2015. Created on May 20, 2013.
Edited by jiv_e, Wejoko, i.bajrai, laughnan. Log in to edit this page.

For using the Search API Solr Search module, you first need a Solr server with the appropriate configuration files. For that, you have two options: either installing Solr on your own server, or purchasing a server instance at a Solr hosting provider.

The most important thing to remember, for both variants, is to configure the Solr server with the correct configuration files (see below).

Using a hosted solution

Using a hosted solution has the big advantage of requiring no expertise in Solr. There are a number of Solr hosts which either support the Search API directly or allow you to upload your own configuration files. A few of them are listed on the Search API Solr Search project page, but the list is surely incomplete (and might also be out-dated). One thing to watch out for (except for either explicit support of the latest version of Search API Solr Search or support of uploading custom configs) is that the connection shouldn't require any advanced authentication mechanism, like a certificate or appending GET parameters to all requests, as this currently isn't supported by the module (out of the box). Currently, only Basic HTTP Authentication and HTTPS are supported.

And again: remember to use the correct configuration files!
Then, just enter the connection information for Solr (which you should have received from the Solr host) when creating the Search API server and you should be good to go.

Installing Solr manually

While Solr is simply available through the package manager in most popular Linux distributions, the versions in the distribution repositories are usually very out-dated (e.g., the latest Ubuntu LTS version, 12.04, contains Solr 1.4). Also, installing and running Solr isn't very hard, so installing a Solr server manually is usually the better choice. For installing Solr 3.6 on Ubuntu, you may reference these instructions, they are easily to follow and should work in most cases.

Basic setup

As a pre-requisite for running your own Solr server, you'll need Java 6 or higher.

Download the latest version of Solr and unpack the archive somewhere outside of your web server's document tree. (The latest supported version can be seen by looking inside the solr-conf/ directory in the module, or looking at its README.txt file.)

For small websites, using the example application, located in $SOLR/example/, usually suffices. In any case, you can use it for developing and testing. The following instructions will assume you are using the example application, otherwise you should be able to substitute the corresponding paths.

Note: The Solr 4.3+ example application is currently not completely supported with the configuration files included in this module, due to a slight change in directory structure. To fix this, simply copy, move or symlink the contrib/ directory from the top level of the extracted Solr package one level down to example/:

$ ln -s $SOLR/contrib $SOLR/example/

(For other directory structures: the contrib/ directory has to be in the directory two levels up from the one which includes the conf/ directory. For help, just start the Solr server and check the log files for WARN messages – they should state in which place Solr expects the directory to be.)

Caution! For production sites, it is vital that you somehow prevent outside access to the Solr server. Otherwise, attackers could read, corrupt or delete all your indexed data. Using the example server WON'T prevent this by default. If it is available, the probably easiest way of preventing this is to disable outside access to the ports used by Solr through your server's network configuration or through the use of a firewall.
Other options include adding basic HTTP authentication or renaming the solr/ directory to a random string of characters and using that as the path.

Config files

Before starting the Solr server you will have to make sure it uses the proper configuration files. These are located in the solr-conf/ directory in this module, in a sub-directory according to the Solr version you are using. Copy all the files from that directory into Solr's configuration directory ($SOLR/example/solr/collection1/conf/ in case of the 4.x example application), after backing up all files that would be overwritten.

Note: In earlier versions of this module, not all necessary files were included in the module package, but only those that differ from Solr's example application. The following files are additionally needed, if not present: elevate.xml, mapping-ISOLatin1Accent.txt, stopwords.txt and synonyms.txt. You have the following options:

  • Use the files from the latest dev version of the module.
  • Just create empty files with their names. In the case of elevate.xml, however, you have to put the text <elevate /> into the file.
  • Use the ones from Solr's example application. This might not be the best option, though, as they contain some example definitions which might lead to undesired behavior. Review their contents before using them!

However, the mapping-ISOLatin1Accent.txt file included in Solr's example application is usually even better suited than the one provided with this module, as it contains a lot of useful character mappings (if you want such conversions to be performed). Therefore, it is recommended that you use the file from Solr's example application in this one case.
For licensing reasons, it is not possible for us to just include that file in our module.

Running Solr

After making sure all necessary config files are in place, you can then start Solr. For the example application, go to $SOLR/example/ and issue the following command (assuming Java is correctly installed):

java -jar start.jar &

Afterwards, go to the Solr admin screen in your web browser to ensure Solr is running correctly.

You can then enable this module and create a new server, using the "Solr search" service class. Enter the hostname, port and path corresponding to your Solr server in the appropriate fields. The default values already correspond to the example application, so you won't have to change the values if you use that. If you are using HTTP Authentication to protect your Solr server you also have to provide the appropriate user and password here.

Installing Solr with Ansible

Ansible is a simple server automation tool. For installing fully functional Apache Solr server instance you can try an Ansible script maintained by jiv_e. It does a lot of stuff including search_api_solr config files placement. See

You can contribute to the project by submitting bug reports, code and documentation! Please help to make it better so no one needs to install Solr by hand.

Looking for support? Visit the forums, or join #drupal-support in IRC.


asauterChicago’s picture

If the host has Solr configured for you, most likely they have Solr configured as a service. So java -jar start.jar will only make someone very confused when it doesn't work. The most likely correct command when running on a host would be: sv restart solr .

jackbravo’s picture

The comment about the instructions not working for solr 4.3+ doesn't seem to be true anymore. And the INSTALL file in the search_api module doesn't mention it. Should we remove it?

pinkonomy’s picture

How is this possible to run Jetty automatically when starting/restarting Apache?
I am using ubuntu 14.04