I recently had to debug Solr 5 to help answer some client questions. With Solr 5, there’s been several fundamental changes to the Lucene/Solr codebase. My previous methods of debugging Solr didn’t work anymore, so I had to figure out anew how to debug Solr 5.

If you try to work with a recent Solr/Lucene codebase you’ll immediately hit a few snags:

Java 7 is deprecated, time to upgrade to Java 8!* Solr is run through the handy ./bin/solr command. No more java -jar start.jar

*turns out you don’t need java 8 for Solr 5, but it has a bug where ant tasks dont run without it!

Install Java 8

Java 7 is EOL, Solr is deprecating Java 7 in the next release. So you’ll of course need to get Java 8 on your machine. I leave this as an exercise to the reader. I prefer OpenJDK unless explicitly told not to by the project. It’s simpler to install and manage on *nixs that I usually work on.

Clone lucene-solr

I always work directly with the Github mirror of the Lucene/Solr project. Using git clone, I create a lucene-solr directory with the latest source code (you may wish to just debug a specific tag):

Note this checks out the trunk, examine the tags to play with a specific 5x+ branch.

Side-by-side Java 7/Java 8

If you want to keep your default Java 7, but use Java 8 just for Lucene/Solr, use direnv. This tool lets you define environment variables such as PATH and JAVA_HOME on a directory-by-directory basis.

With direnv installed, you can define a .envrc file in the lucene-solr directory. Create a .envrc. Here’s what mine looks like which makes Java 8 default for anything under the lucene-solr directory:

export PATH=/usr/lib/jvm/java-8-openjdk-amd64/jre/bin/:/home/doug/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games

You’ll also need to tell direnv to allow per-directory environment variables with direnv allow :

$~/workspace/lucene-solr> direnv allow

Now run java -version and verify you’re using Java 8:

java -version$~/workspace/lucene-solr> java -versionopenjdk version "1.8.0_45-internal"OpenJDK Runtime Environment (build 1.8.0_45-internal-b14)OpenJDK 64-Bit Server VM (build 25.45-b02, mixed mode)

Great! Now you’re ready to get started with Solr 5 development.

Build Solr

With Java 8 working in this directory, you should be able to run the various ant tasks to build Solr 5 and setup IntelliJ project files. Let’s build Solr:

$~/workspace/lucene-solr> cd solr$~/workspace/lucene-solr/solr> ant server

You’ll notice that ant example is deprecated. This was the old way of building a default Jetty infrastructure. Now Solr is just a binary that gets run without worrying about Jetty containers.

Run Solr with local configs

Now under solr, you should have a ./bin directory. This is where the new Solr executable lives. Run ./bin/solr --help for information on all the command line options.

For purely local, non SolrCloud configurations, you’ll just want to run this command pointed at a specific Solr home directory. A directory with a solr.xml at its root, and various collections underneath. To do that, simply pass the -s command with a directory as such:

$~/workspace/lucene-solr/solr> ./bin/solr -f -s /home/doug/workspace/statedecoded/solr_home/

(-f runs in the foreground, not as a daemon)

You’ll quickly hit errors as many deprecated features in your Solr 4 configs are no longer supported. So go mucking headlong into your solr.xml, schema, and solrconfig to clean those up.

Loading Source in IntelliJ

Getting Intellij to work is fairly straightforward. At the root Lucene directory, generate the IntelliJ project files using an ant task:

$~/workspace/lucene-solr/> ant idea

Open IntelliJ, and go to File -> Open . Browse to the lucene-solr directory. The directory should have an Intellij icon, indicating the project files exist.

Once opened, be sure to go to File -> Project Structure and set Java 8 as the default SDK.

Debugging Solr in Intellij

The new /bin/solr lets you pass an -a argument to append Java arguments to Solr. You can use this to add remote debugging configuration like in this example:

$~/workspace/lucene-solr/solr>./bin/solr -f -a "-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=4044" -s /home/doug/workspace/statedecoded/solr_home/

Run this command. It will pause waiting for a debugger to attach ( suspend=y ). In IntelliJ, create a debug configuration in Run -> Edit Configurations . Hit the + button and select Remote . Give this configuration a name, and set the port number to the port number passed in the address command above (here it’d be 4044).

Now start the debugging session, and viola! You should be able to set breakpoints and work in the Solr/Lucene codebase.

Hope this little tutorial was helpful, please get in touch if you see anything that could be improved.