Apache Solr on FreeBSD - The Basics

There is a serious lack of basic documentation on how to use Apache Solr on FreeBSD. Lets change that.

Requirements

• Tested on FreeBSD 14.3
• Test with Apache Solr 9.x

This guide will focus on managing a single Solr instance with no replication or sharding. Therefore there is no need to have a Zookeeper cluster.

System Setup and Installation

Lets create a new ZFS Pool to keep our search data. Using some hints from zfs.guru, we will create a dataset for Solr in our newly created ZFS pool. Compression will be enabled and the mountpoint for the dataset will be in the standard location for FreeBSD. Notice how the pool itself isn't actually mounted.

Adjust the commands below to your environment and needs (ie. replace da1 with an actual block device or vdev)

install -d /var/db/solr
chflags schange /var/db/solr
zpool create -m none -o autoexpand=on  Data da1
zfs create -o mountpoint=/var/db/solr -o compression=lz4 Data/Solr
service zfs enable

The purpose of the chflags command is to prevent the system from writing to the directory if for whatever reason the ZFS dataset is not mounted.

Install Apache Solr from the package

pkg install -y textproc/apache-solr
service solr enable

Ensure the /proc mount is in place for the Java VM:

FSTAB=/etc/fstab; if [ ! $(grep -q "/proc" "${FSTAB}") ]; then echo -e "proc\t/proc\t\t\tprocfs\trw\t\t0\t0" >> $FSTAB; fi
mount /proc

Start Apache Solr

service solr start

By default it will listen on port 8983 on localhost. You can change this to all interfaces by adding SOLR_JETTY_HOST to /usr/local/etc/solr.in.sh.

SOLR_JETTY_HOST="0.0.0.0"

Inside that same file you can change the port number, though you probably should leave it as the default unless you have a good reason. Note, if you see a "-Djetty.host=localhost" flag in this file, just ignore it. Later versions of Apache Solr do not use this flag.

Create a Core

Normally to create a core you'd issue a single command and you'd be all set.

su -m solr -c "/usr/local/solr/bin/solr create -c mycore"

What About ZFS

You don't have to organize your cores into dedicated ZFS datasets, but why not? Sadly the setup process is a little rough. If you are okay with the extra up-front work, it will be worth it in the end.

First create the dataset under the Solr dataset:

zfs create Data/Solr/mycore

You won't be able to use the solr create command since that command copies the template files as a sub-directory in the Solr datastore. Attempting to do so will result in a 'Device busy' error.

Instead you must manually copy things over, create structure, and set permissions.

cp -r /usr/local/solr/server/solr/configsets/_default/conf /var/db/solr/mycore/
install -d -o solr -g solr /var/db/solr/mycore/data

Fix the permissions:

chown -R solr:solr /var/db/solr/mycore

To register it:

Using the CLI (cURL)

curl "http://localhost:8983/solr/admin/cores?action=CREATE&name=mycore&instanceDir=/var/db/solr/mycore"

Result:

{
  "responseHeader":{
    "status":0,
    "QTime":353
  },
  "core":"mycore"
}

Or, using the Web UI

The important part is to make sure your dataset name and core name match exactly.