The following tutorial will explain the setup procedures for installing Solr 4.6 with Tomcat 7 on Debian 7 with Authentication enabled. The instructions should also work for other versions of Solr / Tomcat / Debian and other GNU/Linux environments if the appropriate commands are used.
Additionally, the authentication will allow for using the Solr admin web page remotely without having it publicly accessible.
First off, Java Needs to be installed so that Tomcat and Solr can run. Because Tomcat is a server app, GUI dependencies for Java are not needed, so installing the headless JRE will do.
# apt-get install openjdk-7-jre-headless
Note: Since Debian supports automatic dependency resolution, installing Tomcat 7 directly and having Debian decide how to install Java will result in the system using Java 6 instead of Java 7 for compatibility reasons. However, Java 7 will enable the addition of WebSockets in Tomcat 7, better concurrency, the client/server compiler for faster long-term running applications like Web apps, and a better garbage collector1.
The following command will install Tomcat server, the Tomcat Web Application Manager and the Tomcat Virtual Host Manager so that the proper installation of Solr can be verified later via a nice web page.
# apt-get install tomcat7 tomcat7-admin
Now that Tomcat has been installed, the server should show a welcome page at http://localhost:8080/, assuming Tomcat is running on the same machine. For remote VMs, replace “localhost” with the server IP or domain.
If the page doesn’t load, make sure Tomcat is running:
# service tomcat7 start
Configuring Tomcat manager webapps authentication
The tomcat7-admin package ships with two Tomcat webapps, the Web Application Manager, and the Virtual Host Manager. However, by default, for security reasons, none of them are accessible. Tomcat’s authentication needs to be enabled in order to access these tools.
First, open the tomcat-users.xml configuration file for editing:
# nano /etc/tomcat7/tomcat-users.xml
Before the closing </tomcat-users> element, add the following lines of XML to provide access to both webapps to a single user as identified by the username and password attributes:
<role rolename="manager-gui"/> <role rolename="admin-gui"/> <user username="your_username" password="your_password" roles="manager-gui,admin-gui"/>
Save the file and restart the Tomcat server for the configuration changes to take effect.
# service tomcat7 restart
The manager webapps should now be accessible behind the login prompt at http://localhost:8080/manager/html and http://localhost:8080/host-manager/html.
Download and extract the Solr 4.6.1 tarball:
# curl http://archive.apache.org/dist/lucene/solr/4.6.1/solr-4.6.1.tgz | tar xz
Note: Navigate to the following address for faster mirrors: http://www.apache.org/dyn/closer.cgi/lucene/solr
Next, the Solr example app that comes bundled with the tarball will be set up. To do that, required libraries must be placed into Tomcat’s classpath. On Debian, simply copy the JARs from ~/solr-4.6.1/example/lib/ext to /usr/share/tomcat7/lib.
# cp ~/solr-4.6.1/example/lib/ext/* /usr/share/tomcat7/lib/
Note: Tomcat’s classpath directory contains symlinks to the actual JARs in the /usr/share/java classpath folder. The same can be done if desired, but it doesn’t matter in practice. The apparent structure is only an illusion and the symlinks follow a variety of logics for a variety of reasons. Since Tomcat loads libraries regardless of the filename, copying the JARs directly will do. The JARs can always be updated later by simply copying newer versions and removing the old ones in the same folder.
Next, Solr’s WAR file has to be placed inside Tomcat’s webapps directory so that Tomcat can deploy the Solr app.
# cp ~/solr-4.6.1/dist/solr-4.6.1.war /var/lib/tomcat7/webapps/solr.war
Note that by default, Tomcat deploys WAR files to folders with the same name, so once the app is running, the folder /var/lib/tomcat7/webapps/solr should have been created and the server will run from there.
The final step involves copying the example app’s support files to Tomcat’s Catalina base folder: /var/lib/tomcat7 and updating the folder permissions to give ownership to the Tomcat server.
# cp -R ~/solr-4.6.1/example/solr /var/lib/tomcat7 # chown -R tomcat7:tomcat7 /var/lib/tomcat7/solr
Catalina is Tomcat’s servlet container, or, simply said, the component of the Tomcat server which interacts with Java servlets.
Next, restart the Tomcat server and the Solr app should show up as running in the Web Application Manager at http://localhost:8080/manager/html
If it’s not, restart the server to make sure the app is being deployed correctly.
# service tomcat7 restart
Securing the Solr admin page
By now, the Solr app should be running at http://localhost:8080/solr. If port 8080 is publicly accessible on the server, however, as is the case by default for a public Debian VM, the complete Solr admin page is now accessible to the whole Internet without any restrictions.
To prevent his, shut down the Tomcat server immediately to avoid exposing the system to attacks.
# service tomcat7 stop
Once the server is stopped, it’s time to set up authentication for the Solr admin page. Even if port 8080 is not accessible publicly, it’s a good idea to set up authentication to prevent unauthorized access by other users on the subnet.
To do this, edit the /var/lib/tomcat7/webapps/solr/WEB-INF/web.xml file. This file contains the configurations for the deployed Solr app.
# nano /var/lib/tomcat7/webapps/solr/WEB-INF/web.xml
In this file, insert the following before the closing </web-app> element:
<security-constraint> <web-resource-collection> <web-resource-name>Solr GUI Authentication</web-resource-name> <url-pattern>/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>solr-gui</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> </login-config>
This will add app-wide authentication in plain HTTP with a basic password prompt for the role solr-gui.
Next, edit the /etc/tomcat7/tomcat-users.xml file to add the role to the user previously created:
<role rolename="manager-gui"/> <role rolename="admin-gui"/> <user username="your_username" password="your_password" roles="manager-gui,admin-gui,solr-gui"/>
Start the Tomcat server again, and the Solr app at http://localhost:8080/solr should now be accessible with the same username and password previously created. Of course, a separate username and password may be created if desired.
This is it. The server should now be running a fully functional Tomcat + Solr setup.