External Solr for XWiki in Docker
Explanation
By default, the XWiki Docker image uses the Solr instance embedded in XWiki, which needs no setup at all. The image also lets you point XWiki at a standalone Solr server running in its own container, which is the recommended setup for a large wiki.
Why Use an External Solr
The embedded Solr instance exists for ease of use, and running Solr embedded is not recommended by the Solr team. Externalizing it becomes worthwhile as a wiki grows:
- Memory: Solr uses a lot of memory, and the embedded instance takes it from the XWiki JVM heap.
- Speed: a standalone Solr instance is generally faster than the embedded one. The difference is barely noticeable on a small wiki, but memory issues and slow search results are a sign that a wiki has outgrown the embedded instance.
- Storage: Solr and Lucene are filesystem intensive, so the speed of the drive holding the index matters. Placing the index on an SSD can give a noticeable boost.
- Tooling: a standalone Solr ships a web UI, along with monitoring and test tools.
See the Solr Search API documentation for the XWiki side of this, and Solr Performance Problems for Solr-specific performance details.
How the Image Configures a Remote Solr
XWiki 17.10.11+, 18.4.3+, 18.6.0+
The image reads the SOLR_BASE_URL environment variable, which holds the full base URL of the Solr server, so it can carry a scheme, a host, a port and a path, for example http://solr-xwiki:8983/solr. When that variable is set, the container writes the following into xwiki.properties the first time it starts:
solr.type=remote
solr.remote.baseURL=<the value of SOLR_BASE_URL>When SOLR_BASE_URL is left empty, which is the default, XWiki keeps using its embedded Solr.
XWiki <17.10.11, <18.4.3, <18.6.0 Earlier images have INDEX_HOST and INDEX_PORT variables in place of SOLR_BASE_URL. They can only build an http://host:port/solr/xwiki URL, and they write the deprecated single-core solr.remote.url property, which XWiki stopped using in 12.2 when it moved to several cores, so a remote Solr cannot be configured through them. On such an image, provide your own xwiki.properties file holding the two properties above instead.
The Solr Cores XWiki Needs
XWiki stores its indexes in four Solr cores: search, events, ratings and extension_index. XWiki does not create them on a remote server, because the Solr REST API is too limited for that, so all four must already exist on the Solr server when XWiki starts.
Each core is a directory of the Solr home named xwiki_<core>_<solrMajorVersion>, for example xwiki_search_9. The xwiki part comes from the solr.remote.corePrefix property, so change it in the directory names too if you change that property. The version suffix matches the major version of the Solr server, and XWiki supports the current and the previous Solr major version.
The Provided Solr Image
Creating those four cores by hand, with the schemas XWiki expects, is tedious, so the contrib/solr directory of the xwiki-docker repository holds a Dockerfile and a solr-init.sh script that build a ready-to-use Solr image, as follows:
- It is built from the official Solr image, so everything documented there applies to it as well.
- At build time it downloads XWiki's pre-built Solr core packages, one per core. The XWIKI_VERSION build argument selects the XWiki version they come from, and it must match the version of XWiki that uses the server.
- At run time, before Solr starts, solr-init.sh lays those cores into the Solr home. It leaves alone the cores that are already there, so restarting a container whose index is persisted never overwrites an existing index.
- It enables Solr's analysis-extras module. The schema of the XWiki search core relies on language analyzers, such as the Polish stemmer, that this module provides and that the core packages cannot bundle. Without it, the search core fails to load.
The provided Dockerfile starts from solr:9, which matches the cores installed by the core packages.
Persisting the Index
The Solr server keeps its data in /var/solr inside the container, so that is the path to mount to keep the index across container recreations. A bind-mounted host directory has to be owned by the Solr user and group of the image, which is 8983:8983:
chown 8983:8983 /my/path/solrThe index is derived data: if it is lost, XWiki indexes the wiki again. On a large wiki that takes a long time, which is the reason to persist it.
FAQ
Do I need an external Solr?
No. The embedded Solr is fine for a small wiki. Consider an external one when the wiki grows and you start seeing memory pressure or slow search results.
Why doesn't XWiki create the Solr cores itself?
The Solr REST API is too limited to create cores with the schemas XWiki needs, so the cores have to exist on the server before XWiki starts.
Does the external Solr have to run in a container?
No. SOLR_BASE_URL accepts the base URL of any reachable Solr server; a container is simply the easiest way to get one with the XWiki cores installed.
Can I use the official Solr image directly?
Yes, but you then have to install the four XWiki cores yourself, which is exactly what the provided image does on startup.
