External Solr
Supported Solr Versions
See the Solr requirement notes
Install Solr
Refer to the Solr documentation for instructions on setting up Solr on your server.
You will download the Solr package and extract it to a folder of your choosing. Do not start Solr until you have added the ArchivesSpace configuration files.
We strongly recommend a standalone mode installation. No support will be provided for Solr Cloud deployments specifically (i.e. we cannot help troubleshoot Zookeeper).
Create a configset
Before running Solr you will need to setup a configset.
Linux
Using the command line:
Be sure to replace /$path/$to/$solr
with your actual Solr location, which might be something like:
Windows
Right click on your Solr directory and open in Windows Terminal (Powershell).
You should see something like this in response:
Copy the ArchivesSpace Solr configuration files from the solr
directory included
with the release into the $SOLR_HOME/server/solr/configsets/archivesspace/conf
directory.
There should be four files:
- schema.xml
- solrconfig.xml
- stopwords.txt
- synonyms.txt
Note: your exact output may be slightly different.
Setup the environment
From Solr v9 ArchivesSpace requires the use of Solr modules. We recommend using the environment variable option to specify the modules to use:
This environment variable needs to be available to the Solr instance at runtime.
For instructions on how set an environment variable here are some recommended articles:
- https://www.freecodecamp.org/news/how-to-set-an-environment-variable-in-linux
- https://www.java.com/en/download/help/path.html (includes Windows)
Setup a Solr core
With the configset
in place run the command to create an ArchivesSpace core:
Wait for Solr to start (running as a non-admin user):
You can check that Solr is running on http://localhost:8983.
Now create the core:
You should see confirmation:
In the browser you should be able to access the ArchivesSpace schema.
Disable the embedded server Solr instance (optional <= 3.1.1 only)
Edit the ArchivesSpace config.rb file:
Note that doing this means that you will have to backup Solr manually.
Set the Solr url in your config.rb file
This config setting should point to your Solr instance:
If you are not running ArchivesSpace and Solr on the same server, update
localhost
to your Solr address.
By default, on startup, ArchivesSpace will check that the Solr configuration
appears to be correct and will raise an error if not. You can disable this check
by setting AppConfig[:solr_verify_checksums] = false
in config.rb
.
Please note: if you’re upgrading an existing installation of ArchivesSpace to use an external Solr, you will need to trigger a full re-index. See Indexes for more details.
You can now follow the instructions in the Getting started section to start your ArchivesSpace application.
Upgrading Solr
If you are using an older version of Solr than is recommended you may need (if called out in release notes) or want to upgrade. Before performing an upgrade it is recommended that you review:
You should also review this document as the installation steps may include instructions that were not present in the past. For example, from Solr v9 there is a requirement to use Solr modules with instructions to configure the modules using environment variables.
The crucial part will be ensuring that ArchivesSpace’s schema is being used for the
ArchivesSpace Solr index. The config setting AppConfig[:solr_verify_checksums] = true
will perform a check on startup that confirms this is the case, otherwise ArchivesSpace
will not be able to start up.
From ArchivesSpace 3.5+ AppConfig[:solr_verify_checksums]
does not check the
solrconfig.xml
file. Therefore you can make changes to it without ArchivesSpace failing
on startup. However, for an upgrade you will want to at least compare the ArchivesSpace
solrconfig.xml
to the one that is in use in case there are changes that need to be made to
work with the upgraded-to version of Solr. For example the ArchivesSpace Solr v8 solrconfig.xml
will not work as is with Solr v9.
After upgrading Solr you should trigger a full re-index. Instructions for this are in Indexes.