Solr and YaCy Integration

Hint: If you are not a developer, just don't care about this topic. Solr is already inside YaCy, just do nothing.

YaCy uses Solr (and other data structures) to store the local search index (while the remote search index is a RWI data structure). The Solr index is deeply/programmatically embedded into YaCy, but it is also possible to use an external Solr index which can then be assigned to YaCy as external storage. This can be activated with one single click if you have a running Solr, configured for YaCy.

The remote index scheme is similar (but extended) to SolrCell; see We added some more generic fields, added a second solr core and therefore we need to use the solr.xml and schema.xml from a YaCy installation.

Use the deep-embedded Solr in YaCy and an external Solr concurrently

This is the default setting. The assignment of a remote Solr and also switching off of the embedded Solr is done in the servlet /IndexFederated_p.html. The embedded Solr is switched on, if the flag "Use deep-embedded local Solr" is switched on.

Use an external Solr or Solr Shards to have a distributed Solr-backend for a single YaCy

In the "Solr URL(s)" field of the http://localhost:8090/IndexFederated_p.html servlet, you can enter several Solr addresses. If there is more than one Solr assigned, these are accessed as a 'Shard'. This will cause that each document is hashed using the document id and stored only in one of the shards. If a query to Solr is made, then all shards are queried concurrently and the results are merged.

Concurrent usage of the embedded Solr and an external Solr or Solr Shard

It is possible to leave the "Use deep-embedded local Solr" flag switched on while using an external Solr. Then each document is stored in the local and the remote Solr. If a document is searched, this is done concurrently in the local and remote Solr as if they are a Solr Shard.

How to deploy an external Solr for YaCy

The deployment needs two steps: (1) embedd Solr into a servlet environment, (2) configure Solr for YaCy. Both is described in each of the following three options: you can choose between Jetty and Tomcat as servlet container, do only one of the following three:

Use the example-deployment in a Solr package

This is probably the easiest and fastest way to test a YaCy-Solr connection. Don't do this for a production environment; one of the next two options is better for this. The following steps uses Solr 4.1.0; you can use the most recent version as well.

cp ~/yacy/defaults/solr/solr.xml ~/solr-4.1.0/example/solr/collection1/conf/
mkdir ~/solr-4.1.0/example/solr/webgraph
cp -R ~/solr-4.1.0/example/solr/collection1/conf ~/solr-4.1.0/example/solr/webgraph/conf
cp ~/yacy/defaults/solr/schema.xml ~/solr-4.1.0/example/solr/collection1/conf/
cp ~/yacy/defaults/solr/schema.xml ~/solr-4.1.0/example/solr/webgraph/conf/

or, using the explicit schema definition which can be extracted from the YaCy API; start YaCy (if not already running) and execute the following commands:

~/yacy/bin/ /api/schema.xml?core=collection1 > ~/solr-4.1.0/example/solr/collection1/conf/schema.xml
~/yacy/bin/ /api/schema.xml?core=webgraph > ~/solr-4.1.0/example/solr/webgraph/conf/schema.xml
cd ~/solr-4.1.0/example/ && java -jar start.jar

Solr is then running at

Deploy Solr in Tomcat

First you must download and decompress tomcat 6. In this example you install tomcat to your home directory at ~/tomcat/

cd ~
tar xfz apache-tomcat-6.0.37.tar.gz
mv apache-tomcat-6.0.37 tomcat

To deploy a solr container, download a solr package and copy the relevant files to the correct tomcat subdirectory:

cd ~/tomcat
tar xfz solr-4.5.1.tgz
cp solr-4.5.1/dist/solr-4.5.1.war .
cp -R solr-4.5.1/example/solr yacyindex

We need to copy the YaCy schema and the definition of the second core 'webgraph'. Consider that at ~/yacy you have installed a YaCy peer, then you can simply copy the generic schema file for collection1 to solr:

cp ~/yacy/defaults/solr/schema.xml ~/tomcat/yacyindex/collection1/conf/

Clone the collection1 to get the webgraph core

cp -R ~/tomcat/yacyindex/collection1 ~/tomcat/yacyindex/webgraph

Patch the in ~/tomcat/yacyindex/webgraph/ and replace the line name=collection1 with name=webgraph. Then copy the solr.xml definition for two cores:

cp ~/yacy/defaults/solr/solr.xml ~/tomcat/yacyindex/

Copy the solr logging libraries to the tomcat library folder because Solr uses a different logging in jetty as implemented in solr. In the ~/tomcat directory, do

cp solr-4.5.1/example/lib/ext/* ~/tomcat/lib/

To deploy Solr with the YaCy configuration you must create a Tomcat Context fragment. This is a file within the conf subdirecty which is created once tomcat was started. Therefore we start tomcat now:


Look at the path ~/tomcat/conf/Catalina/localhost which was now created. Thats the place where we create the Tomcat Context fragment. You need the absolute path to the tomcat installation directory which we consider as /home/administrator/tomcat in this example. Create a file in /home/administrator/tomcat/conf/Catalina/localhost/solr4yacy.xml with the following content:

<?xml version="1.0" encoding="utf-8"?>
<Context docBase="/home/administrator/tomcat/solr-4.5.1.war" debug="0" crossContext="true">
  <Environment name="solr/home" type="java.lang.String" value="/home/administrator/tomcat/yacyindex" override="true"/>

Restart tomcat to activate this configuration

~/tomcat/bin/ && ~/tomcat/bin/

Finished! You can now access Solr with the url http://localhost:8080/solr4yacy/ This is the url which you can set in the "Use remote Solr server(s)" field of the /IndexFederated_p.html servlet in YaCy to attach the solr-in-tomcat to YaCy as remote storage server. When doing this you may want to remove the flag "Use deep-embedded local Solr" so this remote solr becomes the single storage point for the YaCy search index.

User Administration and Search Index Access Protection

Tomcat can add a password protection to web pages. There is i.e. a default manager web application available at http://localhost:8080/manager/html which cannot be accessed without setting a role and a user name for this. We will activate the manager to test the password protection: write the new role "manager" to the file ~/tomcat/conf/tomcat-users.xml and set a password, i.e.

<?xml version='1.0' encoding='utf-8'?>
  <role rolename="manager"/>
  <user username="admin" password="tomcat" roles="manager"/>

Re-start tomcat, then open http://localhost:8080/manager/html and manage solr applications there. Log-in with the user name 'admin' and the password 'tomcat'. We will use this now to access our YaCy search index in Solr. To do this, we need access rules defined in the web.xml configuration file to declare a role to be protected. We will call this role 'user' and the paths to be all paths within tomcat. Open the file ~/tomcat/conf/web.xml and add the following lines at the end before the closing tag \</web-app>:


To use the new role 'user', we add an account in the file ~/tomcat/conf/tomcat-users.xml. Add the following lines to \<tomcat-users>:

  <role rolename="user"/>
  <user username="yacyadmin" password="yacy123" roles="user"/>

and restart tomcat. You can now access Solr with the url http://yacyadmin:yacy123@localhost:8080/solr4yacy/ This is the url which you can set in the "Use remote Solr server(s)" field of the /IndexFederated_p.html servlet in YaCy. The account:password encoding in the url is used by YaCy to access the solr index within tomcat.

Copy the deeply-embedded Solr Index to an external Solr

This is easy, just copy the Solr directory in DATA/INDEX/\<network>/SEGMENTS/solr_40 into the solr data directory of your remote Solr installation. You can also do this using a script during runtime. Call


which causes that YaCy creates a tar.gz file of the solr_40 directory during runtime and the script returns the file path to this tar.gz file. This filename can then be processed further with your own copy-and-deploy script to fill a remote Solr with that.

For cluster solr usage, see Solr Cloud instructions

Converted from, may be outdated