Configuration¶
SMUI may be configured by passing environment variables to its docker container. The following section describes all configuration parameters.
Note
Environment variables are the preferred way to configure your
production environment. During development (i.e. outside a docker
environment) it is possible to use a local smui-dev.conf file
(see the development setup documentation).
The following sections describe application configs in more detail.
Basic settings¶
The following settings can (and should) be overwritten on
application.conf in your own smui-prod.conf or in your deployment,
using environment variables:
Config key |
Environment variable |
Description |
Default |
|---|---|---|---|
|
|
JDBC database driver |
|
|
|
Database host and optional connection parameters (JDBC connection string). |
|
|
|
Database user |
|
|
|
Database password |
|
|
|
Path to temp file (i.e. where to output the generated |
|
|
|
LIVE |
|
|
|
Only necessary for git deployment (see git deployment documentation). |
|
|
|
Bare filename of the common |
|
|
|
Virtual local Solr instance. WARNING: Deprecated as of v3.4, will be replaced soon. |
|
|
|
Encryption key for server/client communication (Play 2.6 standard). This positively needs to be set to a high-entropy value in production environments. |
WARNING: insecure default. |
SMUI with SQLite (in a Docker setup)¶
To use SMUI with SQLite in a Docker setup, you need to:
Make sure the SQLite database is read/write mounted to the SMUI Docker container.
Use the correct JDBC driver for SQLite with a URL pointing to the mounted database file, e.g.
NOTE: Play is not good in handling SQLite out-of-the-box. We need to disable locks for Play database evolutions. A custom-application.conf is therefore also needed. It contains:
include "application.conf"
play.evolutions.useLocks=false
This is the complete command to run a SMUI container with a SQLite DB and the necessary custom-application.conf (NOTE: environment variables for the CMD must be set in the environment starting SMUI).
docker run -p 9000:9000 \
--mount type=bind,source=/PATH/TO/local_sqlite_smui.db,target=/smui/smui.db \
--mount type=bind,source=/PATH/TO/custom-application.conf,target=/smui/conf/custom-application.conf \
-e SMUI_DB_JDBC_DRIVER=org.sqlite.JDBC \
-e SMUI_DB_URL=jdbc:sqlite:/smui/smui.db \
querqy/smui \
java -Dpidfile.path=$SMUI_CONF_PID_PATH -Dlogback.configurationFile=$SMUI_CONF_LOGBACK_XML_PATH -Dhttp.port=$SMUI_CONF_HTTP_PORT -Dconfig.file="/smui/conf/custom-application.conf" -jar /smui/search-management-ui-assembly-$SMUI_VERSION.jar
Advanced configuration¶
The following sections describe the configuration of:
application behaviour / feature toggles (e.g. rule tagging)
details and options for the deployment (of Querqy’s
rules.txtfile)authentication
The following tables only list the config keys as defined in the SMUI application.conf file.
See the file for the mappings of config keys to environment variables
(e.g. SMUI_DB_JDBC_DRIVER environment variable sets db.default.driver).
Feature toggles¶
The following settings are optional and define the general SMUI behaviour:
Config key |
Description |
Default |
|---|---|---|
|
Show UP(+++) fields instead of separated rule and intensity fields. |
|
|
Offer a separated “Solr Field” input to the user (UP/DOWN, FILTER). |
|
|
With every exported search input, add an additional |
|
|
Separate decompound synonyms ( |
|
|
Path to productive querqy |
Example content, that needs to be adjusted, if split for decompound rules.txt has been activated. |
|
Make separated deployments PRELIVE vs. LIVE possible (and display a button for that on the frontend). |
|
|
PRELIVE |
|
|
Host and port (e.g. |
Empty. In case core reload on PRELIVE deployments should be triggered, this needs to be set. |
|
Separate decompound synonyms for PRELIVE (see above). |
|
|
If set to |
|
|
Path to an optional custom script (see above). |
Example content, that needs to be adjusted, if a custom deployment script is activated. |
|
Should tagging feature be activated. |
|
|
Path to optional file, that provides pre-defined rule tags (see “Configure predefined rule tags”). |
|
|
Target URL of simple logout button (see “Configure Authentication”). |
|
|
Activate spelling items: Add spelling items to maintain common misspellings using the Querqy replace rewriter. The spelling items are exported in a separate replace_rules.txt that is uploaded to Solr. |
|
|
Activate list limitation: Limits the list of visible items to the configured number and shows toggle button (“show more/less”). Set value to -1 to deactivate list limitation. |
|
|
Path to temp file (when |
|
|
|
|
|
PRELIVE |
|
|
WARNING: Deprecated as of v3.14, will be replaced soon (see github.com comment on PR#83). Default username for being displayed on the frontend, if no username is available (e.g. for event history). |
|
|
Persist an event history for all updates to the search management configuration, and provide an activity log for the search manager. WARNING: If this setting is changed over time (especially from |
|
|
Provide custom mapping / step sizes for UP/DOWN boosting/penalising values as JSON (used, if |
|
|
Target environment configuration (e.g. for preview links). See below for details. |
Empty target environment. NOTE: There will come a dummy config showcasing this feature withz upcoming (majo) releases. |
Note
The above described feature toggles are passed to SMUI’s docker container using according environment variables. The mappings can be found in the application.conf.
Custom UP/DOWN dropdown mappings (optional)¶
SMUI makes life easier when dealing with UP/DOWN boosting/penalising intensities.
It translates raw values passed to querqy to a more comprehensible format to
the search manager working with +++ and --- on the frontend.
By default, a typical intensity range from 500 to 5 is covered, which
should work with most search engine’s (e.g. Solr) schema configurations and the according querqy setup.
However, if SMUI’s default does not match the specific needs, the default can be adjusted.
This can be achieved by passing a JSON object describing the desired custom UP/DOWN dropdown
mappings to SMUI while using the toggle.ui-concept.custom.up-down-dropdown-mappings configuration.
The JSON is passed as an escaped string, which is then validated by SMUI.
Note: If for any reason your custom mappings do not apply, check SMUI’s (error) logs, as it is likely, that the validation yielded an error.
Example configuration setting:
toggle.ui-concept.custom.up-down-dropdown-mappings="[{\"displayName\":\"UP(+++++)\",\"upDownType\":0,\"boostMalusValue\":750},{\"displayName\":\"UP(++++)\",\"upDownType\":0,\"boostMalusValue\":100},{\"displayName\":\"UP(+++)\",\"upDownType\":0,\"boostMalusValue\":50},{\"displayName\":\"UP(++)\",\"upDownType\":0,\"boostMalusValue\":10},{\"displayName\":\"UP(+)\",\"upDownType\":0,\"boostMalusValue\": 5},{\"displayName\":\"DOWN(-)\",\"upDownType\":1,\"boostMalusValue\": 5},{\"displayName\":\"DOWN(--)\",\"upDownType\":1,\"boostMalusValue\": 10},{\"displayName\":\"DOWN(---)\",\"upDownType\":1,\"boostMalusValue\": 50},{\"displayName\":\"DOWN(----)\",\"upDownType\":1,\"boostMalusValue\": 100},{\"displayName\":\"DOWN(-----)\",\"upDownType\":1,\"boostMalusValue\": 750}]"
Note that all attribute/value quotation marks in the JSON string need to be escaped. The equivalent docker startup argument would be (command line):
docker run \
...
-e SMUI_CUSTOM_UPDOWN_MAPPINGS="[{\"displayName\":\"UP(+++++)\",\"upDownType\":0,\"boostMalusValue\":750},{\"displayName\":\"UP(++++)\",\"upDownType\":0,\"boostMalusValue\":100},{\"displayName\":\"UP(+++)\",\"upDownType\":0,\"boostMalusValue\":50},{\"displayName\":\"UP(++)\",\"upDownType\":0,\"boostMalusValue\":10},{\"displayName\":\"UP(+)\",\"upDownType\":0,\"boostMalusValue\": 5},{\"displayName\":\"DOWN(-)\",\"upDownType\":1,\"boostMalusValue\": 5},{\"displayName\":\"DOWN(--)\",\"upDownType\":1,\"boostMalusValue\": 10},{\"displayName\":\"DOWN(---)\",\"upDownType\":1,\"boostMalusValue\": 50},{\"displayName\":\"DOWN(----)\",\"upDownType\":1,\"boostMalusValue\": 100},{\"displayName\":\"DOWN(-----)\",\"upDownType\":1,\"boostMalusValue\": 750}]"
...
Preview search queries (optional)¶
Preview links can be configured using the smui.target-environment.config in your custom application.conf.
Here is an example of a multi tenant, multi language preview configuration.
NOTE: The JSON structure is encoded into the HOCON syntax (used by Play / typesafe) as a multiline string:
smui.target-environment.config="""{
"LIVE": {
"de": [
{
"rulesCollection": "MainTenantDE",
"tenantTag": null,
"previewUrlTemplate": "https://www.example.com/de/main-tenant/search?query=$QUERY"
}, {
"rulesCollection": "AlternativeTenantDE",
"tenantTag": "tenant:ALTERNATIVE",
"previewUrlTemplate": "https://www.example.com/de/alternative-tenant/search?query=$QUERY"
}
],
"fr": [
{
"rulesCollection": "MainTenantFR",
"tenantTag": null,
"previewUrlTemplate": "https://www.example.com/fr/main-tenant/search?query=$QUERY"
}, {
"rulesCollection": "AlternativeTenantFR",
"tenantTag": "tenant:ALTERNATIVE",
"previewUrlTemplate": "https://www.example.com/fr/alternative-tenant/search?query=$QUERY"
}
]
},
"PRELIVE": {
...
}
}"""
The first level of the JSON describes the deployment instance that the preview links points to.
Next is a free-definable organizational identifier - typically encoding the language. Then follows the preview link configuration itself.
Preview links are tight to a rules collection, and might be scoped to specific tenants.
The links are rendered using the magic $QUERY symbol in the URL template.
NOTE: TODO As of v3.15 this will be the designated structure for the deployment description in the future.
Authentication¶
SMUI is shipped with HTTP Basic and JWT Authentication support.
Basic Authentication¶
This is telling every controller method (Home and ApiController) to use
the according authentication method as well as it tells SMUI’s
BasicAuthAuthenticatedAction username and password it should use.
Basic Auth can be turned on in the extension by configuring an
smui.authAction in the config file, e.g.:
# For Basic Auth authentication, use SMUI's BasicAuthAuthenticatedAction (or leave it blanked / commented out for no authentication), e.g.:
smui.authAction = controllers.auth.BasicAuthAuthenticatedAction
smui.BasicAuthAuthenticatedAction.user = smui_user
smui.BasicAuthAuthenticatedAction.pass = smui_pass
WARNING: Deprecated as of v3.14. BasicAuth support will be removed soon (see github.com comment on PR#83).
JWT Authentication¶
smui.authAction="controllers.auth.JWTJsonAuthenticatedAction"
Config key |
Description |
Default |
|---|---|---|
|
The URL to the login page (e.g. https://loginexample.com/login.html?callback=https://redirecturl.com) |
|
|
Name of cookie that contains the Json Web Token (JWT) |
|
|
The public key to verify the token signature. |
|
|
The algorithms that should be used for decoding (options: ‘rsa’, ‘hmac’, ‘asymmetric’, ‘ecdsa’) |
|
|
Activation of authorization check |
|
|
The JSON path to the roles saved in the JWT |
|
|
Roles (comma separated) of roles, that are authorized to access SMUI |
|
Example of decoded Json Web Token:
{
"user": "Test Admin",
"roles": [
"admin"
]
}
Logout¶
In this setup, SMUI can provide a simple logout button that simply sends the user to a configured target URL:
smui.auth.ui-concept.simple-logout-button-target-url="https://www.example.com/logoutService/"
Custom Authentication¶
You can also implement a custom authentication action and tell SMUI to decorate its controllers with that, e.g.:
smui.authAction = myOwnPackage.myOwnAuthenticatedAction
See Developing Custom Authentication for details.
Options for rules deployment¶
Deploying rules.txt via cp/scp¶
The default deployment script supports using cp or scp file transfer
as methods to deploy the rules.txt and replace_rules.txt and triggers a Solr core on the
target system, if configured accordingly. Its behaviour is controlled
using the config variables above, e.g.:
docker run \
...
-e SMUI_2SOLR_DST_CP_FILE_TO=remote_user:remote_pass@remote_host:/path/to/live/solr/defaultCore/conf/rules.txt \
-e SMUI_2SOLR_SOLR_HOST=remote_solr_host:8983 \
-e SMUI_DEPLOY_PRELIVE_FN_RULES_TXT=/mnt/prelive_solr_depl/rules.txt \
-e SMUI_DEPLOY_PRELIVE_SOLR_HOST=docker_host:8983 \
...
-v /path/to/prelive/solr/defaultCore/conf:/mnt/prelive_solr_depl
...
querqy/smui
In this particular example, the LIVE instance of Solr runs on
remote_solr_host and can be reached by remote_user on
remote_host for rules.txt deployment (NOTE: remote_host as
well as remote_solr_host might even be the same instance, but just
have differing network names). scp will be chosen by the default
deployment script. In contrast to that, the PRELIVE instance of Solr
resides on the docker_host. File deployment is ensured using an
according docker volume mount. cp will be chosen.
Note
The example above also accounts for
SMUI_TOGGLE_DEPL_DECOMPOUND_DST and
SMUI_DEPLOY_PRELIVE_FN_DECOMPOUND_TXT, when
SMUI_TOGGLE_DEPL_SPLIT_DECOMPOUND is set to true.
Note
The example above also accounts for
SMUI_2SOLR_REPLACE_RULES_DST_CP_FILE_TO and
SMUI_DEPLOY_PRELIVE_FN_REPLACE_TXT, when
SMUI_TOGGLE_SPELLING is set to true.
Deploying rules.txt to a git target¶
The SMUI docker container comes with an alternative
deployment script for deployment to git, which is located under
conf/smui2git.sh.
Note
Your rules.txt repository needs to be initialised with (at least) the empty files,
you would like to get managed by SMUI on the master branch (or branch you would like SMUI to deploy to).
The conf/smui2git.sh main deployment script uses the
alternative git deployment script, in case a GIT deployment target
is supplied (for the specific target system). You can use the following
setting to force git deployment for the LIVE stage, e.g. (command
line):
In the docker container the git deployment will be done in the
/tmp/smui-git-repo path. You need to make sure, that identification is provided to the SMUI docker
environment:
The following example illustrates how to configure SMUI and pass host’s identity:
docker run \
...
-v ~/.ssh/id_rsa:/smui/.ssh/id_rsa \
-v ~/.gitconfig:/home/smui/.gitconfig \
...
-e SMUI_2SOLR_DST_CP_FILE_TO="GIT" \
-e SMUI_DEPLOYMENT_GIT_REPO_URL="ssh://git@repo-host.tld/smui_rulestxt_repo.git" \
...
querqy/smui
Note
When working with remote git locations, it might be necessary to also add your git repo host to SMUI’s
/home/smui/.ssh/known_hosts.As of v3.11.5 only deployment of the common rules.txt file is supported (neither decompound- nor replace-rules.txt files). Support for that might be added in future releases.
Currently only git deployment to the LIVE instance is possible.
Creating initial data¶
After the first startup of SMUI, initial data can be inserted. SMUI supports a REST interface to PUT admin entities (like the following) into the database. This initial data configures Solr collections.
Solr Collections to maintain Search Management rules for¶
There must exist a minimum of one Solr collection (or
querqy/rules.txt deployment target), that Search Management rules
are maintained for. This must be created before the application can be
used. Example curl (relative to localhost:9000):
curl -X PUT -H "Content-Type: application/json" -d '{"name":"core_name1", "description":"Solr Search Index/Core #1"}' http://localhost:9000/api/v1/solr-index
[...]
NOTE: solr-index/name (in this case core_name1) will be used as
the name of the Solr core, when performing a Core Reload (see
smui2solr.sh).
Initial Solr fields¶
Optional. Example curl (relative to localhost:9000):
curl -X PUT -H "Content-Type: application/json" -d '{"name":"solr-field-1"}' http://localhost:9000/api/v1/{SOLR_INDEX_ID}/suggested-solr-field
[...]
Where solr-field-1 refers to the field in your configured Solr
schema you would like to make addressable to the Search Manager.
{SOLR_INDEX_ID} refers to the index ID created by the solr-index
call above.
Refresh Browser window and you should be ready to go.