Configuring Solr

The way that you configure Alfresco to use Solr depends on how you have installed Alfresco.

If you install Alfresco using the setup wizard, Solr is installed and enabled automatically. Solr is installed in the same Tomcat container as Alfresco, and the connection URL is unchanged from the default. The Solr home is in the Alfresco data directory, which also contains the Solr data files.

If you have an existing Alfresco installation, and you wish to configure it to use Solr search, you need to apply the Solr archive to your web application.

Installing and Configuring Solr

This section describes how to install and configure Solr using the distribution archive file to connect to an existing Alfresco installation using Tomcat.

Note: To confirm which application servers Alfresco supports for running the Solr application on, see the Supported Platforms [10] matrix for your version of Alfresco One.

For Alfresco One 4.2 and 4.2.1, the Solr server is supported only when running in a Tomcat application server. From Alfresco One 4.2.2 onwards, Solr server is supported on JBoss as well.

The distribution archive file is called alfresco-enterprise-solr-4.2.8.zip.

This file contains the following artifacts:

a template SOLR home directory containing solr.xml, which is expected by Solr
Solr WAR file
an example context to wire up in Tomcat
a lib directory with all the required Alfresco and other JARs
two Solr core configurations: one to track the live SpacesStore and one to track items archived from the SpacesStore

You can install Solr either to the same Tomcat application server as Alfresco or a separate Tomcat. The Solr server indexes data in Alfresco by periodically tracking the changes made to Alfresco. It does so by calling a RESTful API that describe the latest transactions to it. The Alfresco server performs searches through the Solr server by issuing queries through a special API. For this reason, there needs to be two-way communication between the Alfresco server and the Solr server. For security reasons, the communication channel between the Alfresco server and Solr server must be secured by means of https encryption and mutual client certificate authentication.

The following instructions use <ALFRESCO_TOMCAT_HOME> to refer to the tomcat directory where Alfresco is installed and <SOLR_TOMCAT_HOME> to the tomcat directory where Solr is installed. These may be the same or different directories, depending on whether you have chosen to install Solr on a standalone server.

Extract the alfresco-enterprise-solr-4.2.8.zip file to a location. For example, <SOLR-ARCHIVE>.
Copy the context.xml file to apache-tomcat-6.0.26\conf\Catalina\localhost\solr.xml.
Edit docBase in the solr.xml file to point to <SOLR-ARCHIVE>\apache-solr-1.4.1.war.

Edit solr/home in XML to point to <SOLR-ARCHIVE>.

For example:

<?xml version="1.0" encoding="utf-8"?>
<Context docBase="<SOLR-ARCHIVE>\apache-solr-1.4.1.war" debug="0" crossContext="true">
   <Environment name="solr/home" type="java.lang.String" value="<SOLR-ARCHIVE>" override="true"/>
</Context>

For each core, edit the solrcore.properties file:
- archive-SpacesStore/conf/solrcore.properties
- workspace-SpacesStore/conf/solrcore.properties
Set the data.dir.root property to the location where the Solr indexes will be stored. You can set the same value for the both cores, and the cores will create the sub-directories.
Ensure that Alfresco has already been started at least once and the <ALFRESCO_TOMCAT_HOME>/webapps/alfresco/WEB-INF directory exists.
By default, a keystore directory is created in <SOLR_ARCHIVE>/alf_data/keystore. Note that at this stage the keystore directory will just be a template, containing standard keys. To secure the installation, you must follow the steps to generate new keys as explained in the Generating Secure Keys for Solr Communication [11] section.
For Unix use:
```
mkdir -p <ALFRESCO_HOME>/alf_data/keystore 

cp <ALFRESCO_TOMCAT_HOME>/webapps/alfresco/WEB-INF/classes/alfresco/keystore/* <ALFRESCO_HOME>/alf_data/keystore 
```
For Windows use:
```
mkdir <ALFRESCO_HOME>\alf_data\keystore 

copy <ALFRESCO_TOMCAT_HOME>\webapps\alfresco\WEB-INF\classes\alfresco\keystore\* <ALFRESCO_HOME>\alf_data\keystore 
```

Configure the Alfresco and Solr tomcat application servers to use the keystore and truststore for https requests by editing the specification of the connector on port 8443 in <ALFRESCO_TOMCAT_HOME>/conf/server.xml and <SOLR_TOMCAT_HOME>/conf/server.xml as shown below:

Note: Remember to replace <SOLR_ARCHIVE>/alf_data/keystore with the full path to your keystore directory.

For example:

<Connector port="8443" URIEncoding="UTF-8" protocol="org.apache.coyote.http11.Http11Protocol" 
SSLEnabled="true"  maxThreads="150" scheme="https" keystoreFile="/opt/alfresco/keystore/ssl.keystore" 
keystorePass="kT9X6oe68t" keystoreType="JCEKS" secure="true" 
connectionTimeout="240000" truststoreFile="/opt/alfresco/keystore/ssl.truststore" 
truststorePass="kT9X6oe68t" truststoreType="JCEKS" clientAuth="want" sslProtocol="TLS" 
allowUnsafeLegacyRenegotiation="true" maxHttpHeaderSize="32768" />

Configure Alfresco to use the keystore and truststore for client requests to Solr by specifying dir.keystore in ALFRESCO_TOMCAT_HOME/shared/classes/alfresco-global. properties.

Note: Remember to replace <SOLR_ARCHIVE>/alf_data/keystore with the full path to your keystore directory.

For example:
```
dir.keystore=<SOLR_ARCHIVE>/alf_data/keystore 
```
Configure an identity for the Alfresco server. In <SOLR_TOMCAT_HOME>/conf/tomcat-users.xml, add the following:

Note: Remember, you can choose a different username, such as the host name of the Alfresco server, but it must match the REPO_CERT_DNAME that you will later specify in the keystore in the Generating Secure Keys for Solr Communication [11] section.

For example:
```
<user username="CN=Alfresco Repository, OU=Unknown, O=Alfresco Software Ltd., L=Maidenhead, ST=UK, C=GB" roles="repository"
 password="null"/>  
```
Configure an identity for the Solr server. In <ALFRESCO_TOMCAT_HOME>/conf/tomcat-users.xml, add the following:

Note: Remember, you can choose a different username but it must match the SOLR_CLIENT_CERT_DNAME that you will later specify in the keystore in the Generating Secure Keys for Solr Communication [11] section.

For example:
```
<user username="CN=Alfresco Repository Client, OU=Unknown, O=Alfresco Software Ltd., L=Maidenhead, ST=UK, C=GB"
 roles="repoclient" password="null"/>  
```
To complete the installation, it is necessary to secure the two-way communication between Alfresco and Solr by generating your own keys. See the Generating Secure Keys for Solr Communication [11] topic.

Generating secure keys for Solr communication

This task describes how to replace or update the keys used to secure communication between Alfresco and Solr, using secure keys specific to your Alfresco installation.

The following instructions assume that Solr has been extracted and a keystore directory has already been created, either automatically by the Alfresco installer or manually by following the instructions in the Configuring Solr [13] section.

If you are applying these instructions to a clustered installation, the steps should be carried out on a single host and then the generated .keystore and .truststore files must be replicated across all other hosts in the cluster.

Obtain the file generate_keystores.sh (for Linux and Solaris) or generate_keystores.bat (for Windows) from the Alfresco Customer Support [14] website.
Edit the environment variables at the beginning of the file to match your environment.
1. If you are updating an environment created by the Alfresco installer, you only need to edit ALFRESCO_HOME to specify the correct installation directory.
2. For manual installations, carefully review ALFRESCO_KEYSTORE_HOME, SOLR_HOME, JAVA_HOME, REPO_CERT_DNAME and SOLR_CLIENT_CERT_DNAME and edit as appropriate. For Weblogic installations, it is necessary to edit the CERTIFICATE_VALIDITY variable so that the certificate expires before the year 2105.
Run the edited script.
You should see the message Certificate update complete and another message reminding you what dir.keystore should be set to in the alfresco-global.properties file.

Solr directory structure

After you have installed Alfresco, several directories and configuration files related to Solr will be available in the Alfresco home directory. This section explains the Solr directory structure.

alfresco\alf_data\solr: This is the Solr home directory. It contains the Solr cores: archive-SpacesStore(for deleted content) and workspace-SpacesStore(for live content). It also contains two configurations files: context.xml and solr.xml.; A Solr core holds one Lucene index and the supporting configuration for that index.

The Solr directory contains the following sub-folders and files:

archive: This directory contains the Lucene index for the archive core.
archive-SpacesStore: This is the configuration directory for the archive core.
docs: This directory contains example update, delete, and commit XML documents.
lib: This directory contains extra libraries that Solr loads on start up. These libraries are used to communicate with Alfresco via CMIS, Alfresco data model or Spring Surf Web Scripts.
workspace: This directory contains the Lucene index for the workspace core.
workspace-SpacesStore: This is the configuration directory for the workspace core.
apache-solr-1.4.1.war: This is the patched version of Apache Solr 1.4.1 Web Application by Alfresco.
apache-solr-1.4.1.war.unpatched: This is the original unpatched version of Apache Solr 1.4.1.
CreateSSLKeystores.txt: This file contains instructions for generating Solr SSL keystores.
HowToSetUpSolr.txt: This file contains instructions on setting up Solr on a dedicated server.
solr.xml: This configuration file specifies the cores to be used by Solr.
context.xml: This configuration file specifies the Solr web application context template to use when installing Solr in separate tomcat server.

alfresco\alf_data\solr\workspace-SpacesStore and alfresco\alf_data\solr\archive-SpacesStore

Both these directories are instance directories for Solr core.

The Solr directory contains the following sub-folders and files:

alfrescoModels: This directory contains all the content models that come out of the box with Alfresco. Any new custom content model added to Alfresco are synced to this directory so that Solr knows about it.
alfrescoResources: This directory contains resource files that specifies what Data Type Index Analyzers should be used for different languages. For example, the default analyzer for Alfresco data type is defined in the dataTypeAnalyzers.properties file as:
```
d_dictionary.datatype.d_text.analyzer=org.alfresco.repo.search.impl.lucene.analysis.AlfrescoStandardAnalyser
```
conf: This is the main configuration directory for Solr core.

alfresco\alf_data\solr\workspace-SpacesStore\conf and alfresco\alf_data\solr\archive-SpacesStore\conf

This is the configuration directory for Solr core. Both these directories are instance directories for Solr core.

The conf directory contains the following configuration files: schema.xml, solrconfig.xml, solrcore.properties, ssl.repo.client.keystore, ssl.repo.client.truststore, ssl-keystore-passwords.properties and ssl-truststore-passwords.properties. To know more about these configuration files, see Solr Configuration Files [15].

Solr configuration files

When you install Alfresco 4.0, several Solr-related configuration files are made available to you. The section lists the Solr configuration files, their location in the Alfresco directory structure and description.

Configuration File	Location	Description
repository.properties	alfresco\tomcat\webapps\alfresco\WEB-INF\classes\alfresco\	This file specifies the Solr-related properties in how Alfresco connects to the Solr server. As the Solr server runs in the same Tomcat instance as Alfresco, the connection properties are setup to connect to a locally running Solr server.
schema.xml	alfresco\alf_data\solr\<core>, where <core> is the location of core's configuration directory, for example alfresco\alf_data\solr\workspace-SpacesStore\conf or alfresco\alf_data\solr\archive-SpacesStore\conf	This file defines the schema for the index including field type definitions with associated analyzers. It contains details about the fields that you can include in your document and also describes how those fields can be used when adding documents to the index or when querying those fields.
solr.xml	alfresco\tomcat\conf\catalina\localhost\	This file defines the Solr web application context. It specifies the location of the Solr war file and sets up the Solr home directory.
solr.xml	alfresco\alf_data\solr	This file specifies the cores to be used by Solr.
solrconfig.xml	alfresco\alf_data\solr\workspace-SpacesStore\conf or alfresco\alf_data\solr\archive-SpacesStore\conf	This file specifies the parameters for configuring Solr. Also, the Solr search components are added to this file.
solrcore.properties	alfresco\alf_data\solr\workspace-SpacesStore\conf or alfresco\alf_data\solr\archive-SpacesStore\conf	This is the property configuration file for a core. Solr supports system property substitution, so properties that need substitution can be put in to this file. There is one solrcore.properties file in each core's configuration directory. For details, see the Solr core configuration properties [16] topic.
context.xml	alfresco\alf_data\solr	This file specifies the Solr web application context template to use when installing Solr in separate tomcat server.
ssl.repo.client.keystore	alfresco\alf_data\solr\workspace-SpacesStore\conf or alfresco\alf_data\solr\archive-SpacesStore\conf	This keystore contains the Solr public/private RSA key pair.
ssl-keystore-passwords.properties	alfresco\alf_data\solr\workspace-SpacesStore\conf or alfresco\alf_data\solr\archive-SpacesStore\conf	This file contains the password information for ssl.repo.client.keystore.
ssl.repo.client.truststore	alfresco\alf_data\solr\workspace-SpacesStore\conf or alfresco\alf_data\solr\archive-SpacesStore\conf	This keystore contains the trusted Alfresco Certificate Authority certificate (which has been used to sign both the repository and Solr certificates)
ssl-truststore-passwords.properties	alfresco\alf_data\solr\workspace-SpacesStore\conf or alfresco\alf_data\solr\archive-SpacesStore\conf	This file contains the password information for ssl.repo.client.truststore.

Solr core configuration properties

The solrcore.properties configuration file is the property configuration file for a Solr core. There is one solrcore.properties file in each core's configuration directory. This section lists the properties of this file, their description, and the default value.

Property Name	Description	Default Value
data.dir.root	This property specifies the top level directory path for the indexes managed by Solr.	C:/Alfresco/alf_data/solr
data.dir.store	This property specifies the directory relative to data.dir.root where the data for this core is stored.	workspace/SpacesStore
enable.alfresco.tracking	This property instructs Solr if it should index Alfresco content in the associated Alfresco repository store or not.	`true`
cache.alfresco.size	This property specifies the Alfresco cache size used internally for PATH looks up.	`100`
max.field.length	This property specifies the maximum number of tokens to include for each field. By default, all tokens are added.	`2147483647`
alfresco.host	This property specifies the host name for the Alfresco instance that Solr should track and index. In a default installation, both Alfresco and Solr runs in the same Tomcat instance and on the same host, so host would be set to local host.	`localhost`
alfresco.port	This property specifies the HTTP port for the Alfresco instance that Solr should track and index.	`8080`
alfresco.port.ssl	This property specifies the HTTPS port for the Alfresco instance that Solr should track and index.	`8443`
alfresco.cron	This property specifies the cron expression that instructs Solr how often to track Alfresco and index new or updated content. The default value indicates that Solr tracks Alfresco every 15 seconds.	`0/15 * * * * ? *`
alfresco.stores	This property specifies the Alfresco repository store that this core should index.	`workspace://SpacesStore`
alfresco.baseUrl	This property configures the base URL to Alfresco web project.	`/alfresco`
alfresco.lag	When Solr tracking starts, it aims to get up to date to the current time (in seconds), less this lag.	`1000`
alfresco.hole.retention	Each track will revisit all transactions from the timestamp of the last in the index, less this value, to fill in any transactions that may have been missed.	`3600000`
alfresco.batch.count	This property indicates the number of updates that should be made to this core before a commit is executed.	`1000`
alfresco.secureComms	This property instructs Solr if it should talk to Alfresco over HTTP or HTTPS. Set to none if a plain HTTP connection should be used.	`https`
alfresco.encryption.ssl.keystore.type	This property specifies the CLIENT keystore type.	`JCEKS`
alfresco.encryption.ssl.keystore.provider	This property specifies the Java provider that implements the `type` attribute (for example, JCEKS type). The provider can be left unspecified and the first provider that implements the keystore type specified is used.
alfresco.encryption.ssl.keystore.location	This property specifies the CLIENT keystore location reference. If the keystore is file-based, the location can reference any path in the file system of the node where the keystore is located.	`ssl.repo.client.keystore`
alfresco.encryption.ssl.keystore.passwordFileLocation	This property specifies the location of the file containing the password that is used to access the CLIENT keystore, also the default that is used to store keys within the keystore.	`ssl-keystore-passwords.properties`
alfresco.encryption.ssl.truststore.type	This property specifies the CLIENT truststore type.	`JCEKS`
alfresco.encryption.ssl.truststore.provider	This property specifies the Java provider that implements the `type` attribute (for example, JCEKS type). The provider can be left unspecified and the first provider that implements the truststore type specified is used.	` `
alfresco.encryption.ssl.truststore.location	This property specifies the CLIENT truststore location reference. If the truststore is file-based, the location can reference any path in the file system of the node where the truststore is located.	`ssl.repo.client.truststore`
alfresco.encryption.ssl.truststore.passwordFileLocation	This property specifies the location of the file containing the password that is used to access the CLIENT truststore, also the default that is used to store keys within the truststore.	`ssl-truststore-passwords.properties`
alfresco.enableMultiThreadedTracking	This property enables/disables multi-threaded tracking.	`true`
alfresco.corePoolSize	This property specifies the pool size for multi-threaded tracking. It is used for indexing nodes.	`3`
alfresco.maximumPoolSize	This property specifies the maximum pool size for multi-threaded tracking.	`-1`
alfresco.keepAliveTime	This property specifies the time (in seconds) to keep non-core idle threads in the pool.	`120`
alfresco.threadPriority	This property specifies the priority that all threads must have on the scale of 1 to 10, where 1 has the lowest priority and 10 has the highest priority.	`5`
alfresco.threadDaemon	This property sets whether the threads run as daemon threads or not. If set to `false`, shut down is blocked else it is left unblocked.	`true`
alfresco.workQueueSize	This property specifies the maximum number of queued work instances to keep before blocking against further adds.	`-1`
alfresco.maxTotalConnections	This property is used for HTTP client configuration.	`40`
alfresco.maxHostConnections	This property is used for HTTP client configuration.	`40`
solr.filterCache.size	This property specifies the maximum number of entries in the Solr filter cache.	`512`
solr.filterCache.initialSize	This property specifies the initial capacity (number of entries) of the Solr filter cache.	`512`
solr.queryResultCache.size	This property configures the Solr result cache.	`1024`
solr.queryResultCache.initialSize	This property configures the Solr result cache.	`1024`
solr.documentCache.size	This property configures the Solr document cache.	`512`
solr.documentCache.initialSize	This property configures the Solr document cache.	`512`
solr.queryResultMaxDocsCached	This property configures the Solr result cache.	`200`
solr.maxBooleanClauses	This property specifies the number of Boolean clauses in a query. It can affect range or wildcard queries that expand to big Boolean queries.	`10000`
alfresco.transactionDocsBatchSize	This property is used for batch fetching updates during tracking.	`100`
alfresco.changeSetAclsBatchSize	This property is used for batch fetching updates during tracking.	`100`
alfresco.aclBatchSize	This property is used for batch fetching updates during tracking.	`10`
solr.query.maximumResultsFromUnlimitedQuery	This property is used to set the maximum number of results returned by Solr queries, therefore, limiting otherwise unconstrained Solr queries to return a finite number of results. This prevents such unconstrained queries from consuming excessive resources. By default, the value is set to the same value as the `system.acl.maxPermissionChecks` property. Note: This property is set in the alfresco-global.properties file, and not in the solrcore.properties file. The Alfresco Share searches use the `<max-search-results>` property to control the number of search results. For more information, see Controlling search results in Share [18]. This property is used for queries without an explicit limit.	`1000`
alfresco.index.transformContent	If this property is set to false, the index tracker will not transform any content and only the metadata will be indexed.	`false`

Solr subsystem

Search is contained within a subsystem, and it has an implementation of either solr or lucene.

The Alfresco Solr search subsystem supports the same query languages as the embedded Lucene subsystem, and the same fields (ID , PARENT) are also available. The following properties in the alfresco-global.properties file are related to Solr and are setup as follows, by default:

### Solr indexing ###
index.subsystem.name=solr
dir.keystore=${dir.root}/keystore
solr.port.ssl=8443

Note: As shown above, note that search has been moved into a subsystem with a solr and lucene implementation.

Activating Solr

This section describes how to activate the Solr search mechanism in a manual Alfresco installation or an upgrade from a previous version.

Global properties file

Open the <classpathRoot>\alfresco-global.properties file.

Set the following properties:

Property	Description
`index.subsystem.name`	The subsystem type value. The `index.subsystem.name` property values are either `solr` or `lucene`.
`solr.host`	The host name where the Solr instance is located.
`solr.port`	The port number on which the Solr instance is running.
`solr.port.ssl`	The port number on which the Solr SSL support is running.

For example, some example properties for activating Solr are:

index.subsystem.name=solr
solr.host=localhost
solr.port=8080
solr.port.ssl=8443

Save the global properties file and restart the Alfresco server.

Share Admin Console

Open the Share Admin Console.

Edit the following properties:

Property	Description
`index.subsystem.name`	Select the subsystem type value as either `solr` or `lucene`.
`solr.host`	The host name where the Solr instance is located.
`solr.port`	The port number on which the Solr instance is running.
`solr.port.ssl`	The port number on which the Solr SSL support is running.

Click Save.

JMX client

To switch between Lucene and Solr in JMX, choose MBeans > Alfresco > Configuration > Search.
Set the manager sourceBeanName to either solr or lucene.
The subsystems have their own related properties. The managed - solr instance exposes the solr.base.url property. The lucene subsystem exposes all the properties that had to be set at start up.
These can now be configured live and the subsystem redeployed.

Eventual consistency

Alfresco 4 introduces the concept of eventual consistency to overcome the scalability limitations of in-transaction indexing.

Alfresco 4 with Solr subsystem, does not to include any transactional indexing operation. In other words, Alfresco 4 removes the requirement to have the database and indexes in perfect sync at any given time and relies on an index that gets updated on a configurable interval (default: 15s) by Solr itself.

The index tracker will take care of polling Alfresco for new transactions and will proceed to update its index. In this sense, indexes will eventually be consistent with the database.

Solr troubleshooting for SSL configurations

When you have an Alfresco installation that requires an SSL configuration, you may encounter some connection issues.

You may see a message on the Tomcat console similar to the following (and may find that Solr search and/or the Solr tracking is not working):

Aug 22, 2011 8:19:21 PM org.apache.tomcat.util.net.jsse.JSSESupport handShake     WARNING: SSL server initiated
renegotiation is disabled, closing connection

This message indicates that one side of the SSL connection is trying to renegotiate the SSL connection. This form of negotiation was found to be susceptible to man-in-the-middle attacks and it was disabled in the Java JSEE stack until a fix could be applied.

Refer to the following link for more information: http://www.oracle.com/technetwork/java/javase/documentation/tlsreadme2-176330.html [19].

Refer also to the following links: http://www.gremwell.com/enabling_ssl_tls_renegotiation_in_java [20] o http://tomcat.apache.org/tomcat-6.0-doc/config/http.html [21].

If your version of Java does not have the fix, you need to re-enabled renegotiation by performing the following steps:

Add the -Dsun.security.ssl.allowUnsafeRenegotiation=true option to JAVA_OPTS.
Add the allowUnsafeLegacyRenegotiation="true" option to the Tomcat SSL connector.