Global Settings

BlackLab Frontend is configured through a file blacklab-frontend.properties (as long as you don't deploy the BlackLab Frontend under a different path/name, see below).
If you don't provide a configuration file, the application will use default values for all settings, detailed below.

Name and Location

You can place the file in any of the following locations, listed here in order of precedence. This largely mirrors the options available for the BlackLab server.

1. BLACKLAB_CONFIG_DIR environment variable
2. $HOME/.blacklab or %USERDIR%/.blacklab (Linux/Windows)
3. /etc/blacklab (Linux only)
4. The directory where the BlackLab Frontend .war file is located

Legacy locations (deprecated)

In order of precedence, the following locations are also checked, but are deprecated and will be removed in a future version:

• CORPUS_FRONTEND_CONFIG_DIR environment variable
• AUTOSEARCH_CONFIG_DIR environment variable
• $HOME or %USERDIR% (Linux/Windows)
• /etc/${context path} (Linux only)

⚠️ Beware of Name / Base-URL / Context Path Changes

The file name and relative location of the blacklab-frontend.properties is actually taken from the context path of the application.
That is, the path under which the Frontend is deployed in the servlet container.

This typically matches the name of the .war file, but not always, some servlet containers allow you to change the context path without renaming the .war file.
Adding extra segments to the context path (e.g. /corpora/frontend/, instead of /blacklab-frontend/) will also add those segments to the file path. For the above example, the config should now be located in ${BLACKLAB_CONFIG_DIR}/corpora/frontend.properties (note the /corpora/frontend in the path).

Examples

.war	Context Path (optional)	Proxy (optional)	Browser URL	Config Location (relative to base dir)
blacklab-frontend.war	—	—	/blacklab-frontend	blacklab-frontend.properties
my-frontend.war	—	—	/my-frontend	my-frontend.properties
any	/test/blacklab-frontend	—	/test/blacklab-frontend	test/blacklab-frontend.properties
any	/TEST/blacklab-frontend	/frisian-corpora → /TEST/blacklab-frontend	/frisian-corpora	TEST/blacklab-frontend.properties

Note:

• The config location is relative to the chosen config directory (see above).
• When using a proxy, the context path is determined by the servlet container, not the browser URL.

Environment Variables

You can also configure the global settings through environment variables, which override the values in the configuration file. All environment variables always need to be prefixed with BF_. There are a few options for the name of the variables:

• the setting name, e.g. BF_blsUrl
• the setting name, but in uppercase, e.g. BF_BLSURL
• the setting name, but with camelCase, dots, and dashes separators replaced with underscores, e.g. BF_BLS_URL
• the internal name of the setting (see below), e.g. BF_BLS_URL_ON_SERVER

A few examples

name in .properties	as-is	uppercase	uppercase with underscores	internal name
debugInfo	BF_debugInfo	BF_DEBUGINFO	BF_DEBUG_INFO	BF_SHOW_DEBUG_CHECKBOX_ON_CLIENT
blsUrl	BF_blsUrl	BF_BLSURL	BF_BLS_URL	BF_BLS_URL_ON_SERVER

Available variable names (full file)

/**
 * Message to display at the top of the page. Note that this may contain HTML. https://github.com/instituutnederlandsetaal/blacklab-frontend/issues/247
 * NULL if not set.
 */
BANNER_MESSAGE("bannerMessage"),
/** Url to reach blacklab-server from this application. Never ends with a slash. */
BLS_URL_ON_SERVER("blsUrl"),
/** Url to reach blacklab-server from the browser. Never ends with a slash. */
BLS_URL_ON_CLIENT("blsUrlExternal"),
/** Where static content, custom xslt and other per-corpus data is stored. Never ends with a slash. */
CORPUS_CONFIG_DIR("corporaInterfaceDataDir"),
/** Name of the default fallback directory/corpus in the PROP_DATA_PATH. Never ends with a slash. */
DEFAULT_CORPUS_CONFIG("corporaInterfaceDefault"),
/**
 * Set the "withCredentials" option for all ajax requests made from the client to the (blacklab/frontend)-server.
 * Passes authentication cookies to blacklab-server.
 * This may be required if your server is configured to use authentication.
 * NOTE: this only works if the frontend and backend are hosted on the same domain, or when the server does not pass "*" for the Access-Control-Allow-Origin header.
 * (BlackLab does pass "*" by default, so you'll need a proxy to make this setup work).
 */
FRONTEND_WITH_CREDENTIALS("withCredentials"),
/** Development mode, allow script tags to load js from an external server (e.g. webpack-dev-server), defaults to ${CF_URL_ON_CLIENT}/js. Never ends in a slash. */
JSPATH("jspath"),
// todo remove and use a file watcher or something
/** Development mode, disable caching of any corpus data (e.g. search.xml, article.xsl, meta.xsl etc) */
CACHE("cache"),
/** Enable/disable the debug info checkbox in the interface */
SHOW_DEBUG_CHECKBOX_ON_CLIENT("debugInfo"),
/**
 * Url to reach the blacklab-frontend servlet (i.e. this) from the browser. Usually not required, but might be necessary when server is behind a proxy,
 * defaults to the servlet context path. Never ends with a slash.
 */
CF_URL_ON_CLIENT("cfUrlExternal"),

/** ClientID for OpenID Connect authentication. Defaults to "blacklab-frontend" */
OIDC_CLIENT_ID("oidc.clientId"),
/** Authority for OpenID Connect authentication. This is usually the root of the oidc server. Ex. for Keycloak, https://login.ivdnt.org/realms/blacklab/ */
OIDC_AUTHORITY("oidc.authority"),
/** Metadata URL for the OpenID Connect server passed in the "oidc.authority" setting. Ex. https://login.ivdnt.org/realms/blacklab/.well-known/openid-configuration */
OIDC_METADATA_URL("oidc.metadataUrl"),

// various settings to copy an auth header from a client request to a blacklab request
// (we forward/proxy various requests to BlackLab, and need to pass the auth/username along)
/** Defaults to "Authorization" */
AUTH_SOURCE_NAME("auth.source.name"),
/**
 * One of "header", "cookie", "attribute" (ajp), "parameter" (query param).
 * Defaults to "header".
 */
AUTH_SOURCE_TYPE("auth.source.type"),
/** Defaults to "Authorization" */
AUTH_TARGET_NAME("auth.target.name"),
/**
 * One of "header", "cookie", "parameter" (query param). Attribute is not supported as creating an AJP request from Java is not possible.
 * Defaults to "header".
 */
AUTH_TARGET_TYPE("auth.target.type");

Example file and default values

The file is reloaded automatically

Changes to the configuration file are applied automatically. The application will detect and use the updated settings without requiring a restart.

WARNING

⚠️ This does not work when the config is mounted inside a docker container from a Windows host (due to how file system events work). In that case, editing the config from within the container should work, or restarting the container will also pick up the changes.

You can leave out any setting, and the BlackLab Frontend will just use the default value for that setting.
The default values are shown in the example file below, which you can use as a template for your own configuration. Some defaults are a little smart and will try to guess the right value based on the context path of the servlet.

# The url under which the back-end can reach BlackLab.
# Separate from the front-end to allow connections for proxy situations
#  where the paths or ports may differ internally and externally.
# If not configured, will mirror the blsUrlExternal property.
blsUrl=http://localhost:8080/blacklab-server/

# The url under which the client can reach blacklab-server.
# I.e. the url for BlackLab as seen in the browser
# If not configured, will mirror the blsUrl property.
blsUrlExternal=/blacklab-server/

# The url under which the client can reach the blacklab-frontend.
# May be needed if the BlackLab Frontend is behind a proxy that changes the url.
# This setting actually defaults to the contextPath of the servlet, so this is just an example.
cfUrlExternal=/blacklab-frontend/

# Optional directory where you can place files to further configure and customize
#  the interface on a per-corpus basis.
# Files should be placed in a directory with the name of your corpus, e.g. files
#  for a corpus 'MyCorpus' should be placed under 'corporaInterfaceDataDir/MyCorpus/'.
# See the manual for more information
corporaInterfaceDataDir=/etc/blacklab/projectconfigs/

# Optional directory for default/fallback settings across all your corpora.
# The name of a directory directly under the corpusInterfaceDataDir.
# Files such as the help and about page will be loaded from here
#  if they are not configured/available for a corpus.
# If this directory does not exist or is not configured,
#  we'll use internal fallback files for all essential data.
corporaInterfaceDefault=default

# Path to frontend javascript files (development setting)
# To load JS from an external server (like webpack-dev-server or vite-dev-server), 
#  so the servlet container server does not need to redeploy/be restarted constantly 
# during development 
jspath=/blacklab-frontend/js

# An optional banner message that shows above the navbar.
# The user can hide this banner, after which it will be hidden for a week.
# Updating the banner message will reset the hidden state for all users.
# Simply remove this property to disable the banner.
bannerMessage=<span class="fa fa-exclamation-triangle"></span> Configure this however you see fit, HTML is allowed here!

# Enable or disable xslt and search.xml caching (development setting)
# This means that the XSLT files, .inc templates and search.xml files will be reloaded every time they are requested. It will also change serverside caching of Corpus metadata info downloaded from BlackLab.
cache=true

# Show or hide the debug info checkbox in the settings menu on the search page.
# N.B. The debug checkbox will always be visible when using webpack-dev-server during development.
# It can also be toggled by calling `debug.show()` and `debug.hide()` in the browser console.
debugInfo=false

# Set the "withCredentials" option for all ajax requests made from the client to the (blacklab/frontend)-server. 
# Passes authentication cookies to blacklab-server.
# This may be required if your server is configured to use authentication.
# NOTE: this only works if the frontend and backend are hosted on the same domain, or when the server does not pass "*" for the Access-Control-Allow-Origin header. 
withCredentials=false

# Make the server side of BlackLab Frontend pass some authentication info to BlackLab 
# The following property is proxied to BlackLab 
# In this case, the Authorization header, which will be sufficient for most needs (basic auth, oauth2, oidc)
# When running behind something like oauth2-proxy, you could set these to x-forwarded-email for example, to pass along the email header from BlackLab Frontend to BlackLab 
# (BlackLab will need its AuthSystem to be configured to use this header as well, of course)

# source.type can be any of "header", "attribute" (java servlet specific), "cookie", "parameter" (AJP only)
# target.type can be any of "header", "attribute", "cookie".   "parameter" is not supported, as java cannot make outgoing requests using AJP.
auth.source.name=Authorization
auth.source.type=header
auth.target.name=Authorization
auth.target.type=header