Motivation: In the Beginning, There Was One Tenant…
When starting a new Apache Solr project, your setup is usually straightforward—one language, one tenant, one tidy schema file.
You get everything running perfectly…
“…and you see that it is good!”
Adding another tenant, say expanding from Germany to Austria, doesn’t create many challenges. You still have similar configurations: same language, same synonyms, same analysis.
“…and you see it’s still good!”
But trouble arises when you grow further—introducing more countries, more languages, and more complex configurations. Synonyms change, text analysis gets complicated with different stemmers, and unique fields pop up everywhere.
Suddenly, your clean configs turn messy and confusing.
“…and you see it’s no good anymore!”
You start leaving marks everywhere in your configs to keep track of what’s specific and what’s shared, feeling more lost by the minute. But relax, there’s an elegant, developer-friendly solution: Jinja2 templating.
The Solution: Enter Jinja2 Templating
If you’re a Solr developer who likes Python, Jinja2 is your friend. With it, you maintain a single, central configuration template, embedding placeholders where tenant-specific differences exist. You never repeat yourself unnecessarily, making everything neat and manageable again.
Here’s how simple it is:
Create one main template for shared config settings.
Use placeholders to mark tenant-specific items.
Define these differences in small, individual tenant-specific files.
Render your configurations automatically, painlessly, with a Python script.
“…and you see that it’s good again!”
How to Use Jinja2 in Your Solr Project (Examples)
You only need to understand three core concepts:
extends: to base tenant configs on a shared template.
set: to define variables unique to each tenant.
block: for inserting full sections unique to certain tenants.
Example: Multilingual schema.xml Config
Step 1: Extend your central template.
{% extends "template.schema.xml" %}
Step 2: Set your tenant-specific placeholders.
In your central template (template.schema.xml), use placeholders clearly:
{{ stem_filter_factory }}
{{ norm_filter_factory }}
Then, in your language-specific file (template.schema.de.xml):
{% set stem_filter_factory %}<filter class="solr.GermanLightStemFilterFactory"/>{% endset %}
{% set norm_filter_factory %}<filter class="solr.GermanNormalizationFilterFactory"/>{% endset %}
And for Dutch (template.schema.nl.xml):
{% set stem_filter_factory %}<filter class="solr.SnowballPorterFilterFactory" language="Dutch"/>{% endset %}
Step 3: Use blocks for entire custom sections.
Central template placeholder:
{% block special_fields %}
{% endblock special_fields %}
In your tenant-specific file, populate as needed:
{% block special_fields %}
<field name="special_a" type"text" indexed="true" stored="true" docValues="true" multiValued="false"/>
<field name="special_b" type"string" indexed="true" stored="true" docValues="true" multiValued="true"/>
<field name="special_c" type"int" indexed="true" stored="true" docValues="true" multiValued="false"/>
{% endblock special_fields %}
If you don’t define the block in the tenant-specific file, it remains empty.
A small Python script neatly handles generating your configurations automatically:
A small Python script automates rendering your final Solr config files:
from jinja2 import Environment, FileSystemLoader
def write_template(pathToTemplate, templateFileName, targetFileName, targetEnv, tenant):
environment = Environment(loader=FileSystemLoader(pathToTemplate))
template = environment.get_template(templateFileName)
content = template.render()
filename = f"{targetEnv}/{tenant}/{targetFileName}"
with open(filename, "w", encoding="utf-8") as message:
message.write(content)
print(f"... wrote {filename}")
- pathToTemplate : defines in which directory your template files are located; one folder per file type (schema, solrconfig, etc.) helps to easily find what you are looking for.
- templateFileName : the file name of the (language or tenant) specific template, e.g. template.schema.de.xml
- targetFileName : the file name of the final config file (schema.xml or solrconfig.xml)
- targetEnv : in this example we also have several different environments, such as “dev,” “qa,” or “prod.” So each of those stages has its own set of config files. This enables you to test new config changes before you deploy and destroy your production environment. 😉
- tenant : For the schema.xml, templates have been set up per language but used for multiple tenants. That’s why it’s not only the tenant. This might be different in your setup, of course, so feel free to adapt how the files are organized.
Now you are ready to call your function to actually render some config files. We do it here for both dev and qa in one step, and for a list of defined tenants. The language code is taken from the tenant name:
for env in ["dev", "qa"]:
for tenant in ["DE-de", "AT-de", "NL-nl"]:
language = tenant.split("-")[1]
pathToTemplate = "templates/schema/"
templateFileName = f"template.schema.{language}.xml"
targetFileName = "schema.xml"
write_template(pathToTemplate, templateFileName, targetFileName, env, tenant)
Note: Ensure directories exist before running this script.
The basic structure should look like this:
Basic directory structure
templates/
schema/
template.schema.de.xml
template.schema.nl.xmL
template.schema.xml
dev/
qa/
generate-config.py
… resulting in the following after execution:
Directory structure after script execution
templates/
schema/
template.schema.de.xml
template.schema.nl.xml
template.schema.xml
dev/
DE-de/
schema.xml
AT-de/
schema.xml
NL-nl/
schema.xml
qa/
DE-de/
schema.xml
AT-de/
schema.xml
NL-nl/
schema.xml
generate-config.py
Now you can set up the same for the solrconfig.xml and render both file types in your code. This will give you a complete config for each environment and each tenant that you can now upload to your Solr installation.
Final Thoughts: Quick Tips for Agile Config Management
Templates are powerful, but during rapid testing, editing configs directly can sometimes speed things up. Once you’re happy, move changes back into templates to effortlessly roll them out.
“…and once again, you’ll see that it’s good!”
Jinja2 templating makes Apache Solr configurations manageable, structured, maintainable, and scalable, letting you efficiently handle complexity without losing your sanity.
