You are viewing a plain text version of this content. The canonical link for it is here.
Posted to solr-commits@lucene.apache.org by Apache Wiki <wi...@apache.org> on 2009/11/26 15:21:17 UTC
[Solr Wiki] Update of "SolrTomcat" by artemgy
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Solr Wiki" for change notification.
The "SolrTomcat" page has been changed by artemgy.
http://wiki.apache.org/solr/SolrTomcat?action=diff&rev1=43&rev2=44
--------------------------------------------------
= Solr with Apache Tomcat =
-
Solr runs fine with [[http://tomcat.apache.org/|Tomcat]], see the instructions in the generic [[SolrInstall|Solr installation]] page for general info before consulting this page.
<<TableOfContents>>
== Simple Example Install ==
-
=== Installing Tomcat 6 ===
-
[[http://tomcat.apache.org/|Apache Tomcat]] is a web application server for Java servlets. These are instructions for manually installing Tomcat 6 on Linux, recommended because distribution Tomcats are either old or quirky.
- Create the ''solr'' user. As ''solr'', extract the [[http://tomcat.apache.org/download-60.cgi|Tomcat 6.0 download]] into `/opt/tomcat6`, hereafter referred to as the ''$CATALINA_HOME'' directory.
+ Create the ''solr'' user. As ''solr'', extract the [[http://tomcat.apache.org/download-60.cgi|Tomcat 6.0 download]] into `/opt/tomcat6`, hereafter referred to as the ''$CATALINA_HOME'' directory.
Edit ''$CATALINA_HOME/conf/tomcat-users.xml'' to enable the manager login as user "tomcat" with password "tomcat" (insecure):
@@ -21, +18 @@
<role rolename="admin"/>
<user username="tomcat" password="tomcat" roles="manager,admin"/>
}}}
-
Start Tomcat with ''$CATALINA_HOME/bin/catalina.sh run''. Tomcat runs on the port defined `$CATALINA_HOME/conf/server.xml`, configured by default to port 8080.
The startup script [[attachment:tomcat6]] can be placed in ''/etc/init.d/tomcat6'' on CentOS/RedHat/Fedora so that you can start Tomcat using ''service tomcat6 start''. Use ''chkconfig'' to enable the tomcat6 service to start on boot.
=== Building Solr ===
-
Skip this section if you have a binary distribution of Solr. These instructions will building [[http://apache.is.co.za/lucene/solr|Solr]] from source, if you have a nightly tarball or have checked out the trunk from subversion at `http://svn.apache.org/repos/asf/lucene/solr/trunk`. Assumes that you have [[http://java.sun.com|JDK 1.6]] already installed.
In the source directory, run `ant dist` to build the .war file under ''dist''. Build the example for the [[http://lucene.apache.org/solr/tutorial.html|Solr tutorial]] by running `ant example`. Change to the 'example' directory, run ''java -jar start.jar'' and visit `localhost:8983/solr/admin` to test that the example works with the Jetty container.
=== Installing Solr instances under Tomcat ===
-
Assuming that Solr 1.3.0 and its ''example'' are built, this is how to install the Solr example as an instance under Tomcat. Multiple instances can run simultaneously, us
Copy the ''example/solr'' directory from the source to the installation directory like ''/opt/solr/example'', herafter ''$SOLR_HOME''. Copy the .war file ''dist/apache-solr-1.3.0.war'' into ''$SOLR_HOME''.
The configuration file ''$SOLR_HOME/conf/solrconfig.xml'' in the example sets ''dataDir'' for the index to be ''./solr/data'' relative to the current directory - which is true for running the Jetty server provided with the example, but incorrect for Tomcat running as a service. Modify the ''dataDir'' to specify the full path to ''$SOLR_HOME/data'':
-
+
- {{{
+ . {{{
<dataDir>${solr.data.dir:/opt/solr/example/data}</dataDir>
- }}}
+ }}}
The ''dataDir'' can also be temporarily overridden with the ''JAVA_OPTS'' environment variable prior to starting Tomcat:
- {{{
+ . {{{
export JAVA_OPTS="$JAVA_OPTS -Dsolr.data.dir=/opt/solr/example/data"
- }}}
+ }}}
Create a Tomcat Context fragment to point ''docBase'' to the ''$SOLR_HOME/apache-solr-1.3.0.war'' file and ''solr/home'' to ''$SOLR_HOME'':
@@ -58, +52 @@
<Environment name="solr/home" type="java.lang.String" value="/opt/solr/example" override="true"/>
</Context>
}}}
-
- Symlink or place the file in ''$CATALINA_HOME/conf/Catalina/localhost/solr-example.xml'', where Tomcat will automatically pick it up. Tomcat deletes the file on undeploy (which happens automatically if the configuration is invalid).
+ Symlink or place the file in ''$CATALINA_HOME/conf/Catalina/localhost/solr-example.xml'', where Tomcat will automatically pick it up. Tomcat deletes the file on undeploy (which happens automatically if the configuration is invalid).
Repeat the above steps with different installation directories to run multiple instances of Solr side-by-side.
- If Tomcat is not already running, start it with ''service tomcat6 start'' or ''$CATALINA_HOME/bin/startup.sh run''. The Solr admin should be available at `http://<host>:8080/solr-example/admin`.
+ If Tomcat is not already running, start it with ''service tomcat6 start'' or ''$CATALINA_HOME/bin/startup.sh run''. The Solr admin should be available at `http://<host>:8080/solr-example/admin`.
=== Single Solr Instance ===
-
If you are sure that you will only ever run one instance of Solr, you can do away with the Context fragment by placing the .war in ''$CATALINA_HOME/webapps/solr-example.war'' and setting the Solr home through a global environment variable prior to starting Tomcat:
{{{
export JAVA_OPTS="$JAVA_OPTS -Dsolr.solr.home=/opt/solr/example"
}}}
-
=== Troubleshooting ===
-
==== Login to Tomcat Management page does not work ====
-
''$CATALINA_HOME/conf/tomcat-users.xml'' may be missing the correct user line.
==== Tomcat Manager does not list Solr ====
-
The Context fragment may be invalid. Examine ''$CATALINA_HOME/tomcat6/logs/catalina.out''.
==== Exceptions when visiting Solr admin ====
-
View ''$CATALINA_HOME/logs/catalina.out'' for a better view of the exceptions. Probably caused by an incorrect path in ''solrconfig.xml'' or the Context fragment, or by an unclean build (run ''ant clean'' and rebuild the source).
== Optional Configuration ==
-
=== Logging ===
-
- For information about controlling JDK Logging (aka: java.util logging) in Tomcat, please consult the Tomcat docs...
+ For information about controlling JDK Logging (aka: java.util logging) in Tomcat, please consult the Tomcat docs... http://tomcat.apache.org/tomcat-6.0-doc/logging.html
- http://tomcat.apache.org/tomcat-6.0-doc/logging.html
=== URI Charset Config ===
If you are going to '''query''' Solr using international characters (>127) using HTTP-GET, you must configure Tomcat to conform to the URI standard by accepting percent-encoded UTF-8.
Edit Tomcat's conf/server.xml and add the following attribute to the correct Connector element: URIEncoding="UTF-8".
+
{{{
<Server ...>
<Service ...>
@@ -107, +92 @@
</Service>
</Server>
}}}
-
This is only an issue when sending non-ascii characters in a query request... no configuration is needed for Solr/Tomcat to return non-ascii chars in a response, or accept non-ascii chars in an HTTP-POST body.
=== Configuring Solr Home with JNDI ===
-
A Tomcat context fragments can be used to configure the JNDI property needed to specify your Solr Home directory.
Just put a context fragment file under $CATALINA_HOME/conf/Catalina/localhost that looks something like this...
$ cat /tomcat55/conf/Catalina/localhost/solr.xml
+
{{{
<Context docBase="/some/path/solr.war" debug="0" crossContext="true" >
<Environment name="solr/home" type="java.lang.String" value="/my/solr/home" override="true" />
</Context>
}}}
-
A few things to keep in mind:
+
- * The "conf/Catalina/localhost" directory may not exist by default in your installation. You may have to create it.
+ * The "conf/Catalina/localhost" directory may not exist by default in your installation. You may have to create it.
- * "/some/path/solr.war" is the absolute path to where ever you want to keep the Solr war using the appropriate syntax for your Operating System. In Tomcat 5.5 and later, the war file must be stored outside of the webapps directory for this to work. Otherwise, this entire Context element is ignored.
+ * "/some/path/solr.war" is the absolute path to where ever you want to keep the Solr war using the appropriate syntax for your Operating System. In Tomcat 5.5 and later, the war file must be stored outside of the webapps directory for this to work. Otherwise, this entire Context element is ignored.
- * "/my/solr/home" should be to where you have createed your Solr Home directory, using the appropriate syntax for your Operating System.
+ * "/my/solr/home" should be to where you have createed your Solr Home directory, using the appropriate syntax for your Operating System.
- * Prior to Tomcat 5.5, a "path" attribute was required for Context elements (starting with 5.5, the path attribute must not be used except when statically defining a Context in server.xml, as it will be inferred from the Context fragment filename.
+ * Prior to Tomcat 5.5, a "path" attribute was required for Context elements (starting with 5.5, the path attribute must not be used except when statically defining a Context in server.xml, as it will be inferred from the Context fragment filename.
=== Enabling Longer Query Requests ===
-
If you try to submit too long a GET query to Solr, then Tomcat will reject your HTTP request on the grounds that the HTTP header is too large; symptoms may include an HTTP 400 Bad Request error or (if you execute the query in a web browser) a blank browser window.
If you need to enable longer queries, you can set the maxHttpHeaderSize attribute on the HTTP Connector element in your server.xml file. The default value is 4K. (See http://tomcat.apache.org/tomcat-5.5-doc/config/http.html)
<<Anchor(MultiWebappJndi)>>
+
== Multiple Solr Webapps ==
-
Tomcat context fragments make configuring multiple Solr webapps (with JNDI) in a single Tomcat server easy.
Just follow the previous instructions for "Configuring Solr Home with JNDI" to create a seperate context fragment file under $CATALINA_HOME/conf/Catalina/localhost for each solr webapp you want to run:
$ cat /tomcat55/conf/Catalina/localhost/solr1.xml
+
{{{
<Context docBase="/some/path/solr.war" debug="0" crossContext="true" >
<Environment name="solr/home" type="java.lang.String" value="/some/path/solr1home" override="true" />
</Context>
}}}
$ cat /tomcat55/conf/Catalina/localhost/solr2.xml
+
{{{
<Context docBase="f:/solr.war" debug="0" crossContext="true" >
<Environment name="solr/home" type="java.lang.String" value="/some/path/solr2home" override="true" />
</Context>
}}}
-
Don't put anything related to Solr under the webapps directory.
- The solr home directories are configured via JNDI in the context fragment, and in the examples above will be {{{/some/path/solr1home}}} and {{{/some/path/solr2home}}}
+ The solr home directories are configured via JNDI in the context fragment, and in the examples above will be {{{/some/path/solr1home}}} and {{{/some/path/solr2home}}} The URLs to the two webapps will be {{{http://host:port/solr1}}} and {{{http://host:port/solr2}}}
- The URLs to the two webapps will be {{{http://host:port/solr1}}} and
- {{{http://host:port/solr2}}}
-
== Tomcat on Windows ==
-
=== Single Solr app ===
-
* Download and install [[http://tomcat.apache.org/|Tomcat]] for Windows using the MSI installer. Install it with the tcnative.dll file. Say you installed it in c:\tomcat\
* Check if Tomcat is installed correctly by going to http://localhost:8080/
* Change the c:\tomcat\conf\server.xml file to add the URIEncoding Connector element as shown above.
* Download and unzip the Solr distribution zip file into (say) c:\temp\solrZip\
- * Make a directory called solr where you intend the application server to function, say c:\web\solr\
+ * Make the "solr home" directory called, where you intend the application server to function, say c:\web\solr\
* Copy the contents of the example\solr directory c:\temp\solrZip\example\solr\ to c:\web\solr\
* Stop the Tomcat service
* Copy the *solr*.war file from c:\temp\solrZip\dist\ to the Tomcat webapps directory c:\tomcat\webapps\
* Rename the *solr*.war file solr.war
- * Use the system tray icon to configure Tomcat to start with the following Java option: -Dsolr.solr.home=c:\web\solr
+ * Configure Tomcat to recognise the solr home directory you created, by adding the Java Option -Dsolr.solr.home=c:\web\solr
+ * either use the system tray icon to add the java option
+ * or manually edit the environment script c:\tomcat\bin\setenv.bat and add it to JAVA_OPTS
* Start the Tomcat service
* Go to the solr admin page to verify that the installation is working. It will be at http://localhost:8080/solr/admin
-
+
=== Multiple Solr apps ===
-
* Download and install [[http://tomcat.apache.org/|Tomcat]] for Windows using the MSI installer. Install it with the tcnative.dll file. Say you installed it in c:\tomcat\
* Check if Tomcat is installed correctly by going to http://localhost:8080/
* Change the c:\tomcat\conf\server.xml file to add the URIEncoding Connector element as shown above.
@@ -206, +186 @@
* Go to the solr admin pages for the 2 webapps to verify that the installation is working. It will be at http://localhost:8080/solr1/admin and http://localhost:8080/solr2/admin
=== 64-bit Note ===
-
The MSI installer that installs Tomcat as a Windows service isn't prepared to support 64-bit Windows out of the box. There are some straightforward workarounds, though. See http://stackoverflow.com/questions/211446/how-to-run-tomcat-6-on-winxp-64-bit
== External Resources ==
-
http://www.ibm.com/developerworks/java/library/j-solr1/
== Troubleshooting Errors ==
It's possible that you get an error related to the following:
+
{{{
SEVERE: Exception starting filter SolrRequestFilter
java.lang.NoClassDefFoundError: Could not initialize class org.apache.solr.core.SolrConfig
@@ -224, +203 @@
path.XPathFactoryConfigurationException: No XPathFctory implementation found for the object model: http://java.sun.com/jaxp/xpath/dom
at javax.xml.xpath.XPathFactory.newInstance(Unknown Source)
}}}
-
This is due to your tomcat instance not having the xalan jar file in the classpath. It took me some digging to find this, and thought it might be useful for others. The location varies from distribution to distribution, but I essentially just added (via a symlink) the jar file to the shared/lib directory under the tomcat directory.