Algolia search
Algolia is a search-as-a-service API that Writerside supports out of the box.
Create Algolia application and search index
Sign up for an Algolia account.
On the Algolia applications page, click Create Application.
Configure application parameters, select a region for your datacenter, and create the application.
On the Algolia application page, go to Create Index.
and clickProvide an informative name and create the index.
On the index page, go to Add an attribute under .
, and clickAdd two attributes:
product
andversion
.Click Review and Save Settings and confirm.
Add Algolia parameters to Writerside build configuration
In your documentation project, open buildprofiles.xml.
Under
<variables>
, specify the following:<algolia-id>
Algolia application ID
<algolia-index>
Algolia index name
<algolia-api-key>
Algolia Search-Only API Key
For example:
<variables> <algolia-id>TGW4GIW73X</algolia-id> <algolia-index>index_name</algolia-index> <algolia-api-key>29effd68f91893202311a653263f1fb8</algolia-api-key> </variables>Commit and push these changes, then build and publish the help instance with these configuration parameters.
Publish your search index to Algolia
To reply to search requests from your help, Algolia needs the search index from the build artifact that you published.
If you do not yet have a TeamCity configuration for building your help artifacts, set it up as described in Build on TeamCity Cloud.
Create a separate build configuration for publishing search indexes to your Algolia application.
Configure it to use the following Docker image:
registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-3This image will run the
help-publication-agent
script.Create a Command line type step with the following command:
env "algolia-key=${'$'}ALGOLIA_KEY" java -jar /opt/builder/help-publication-agent.jar \ update-index \ --application-name ${'$'}ALGOLIA_APP_NAME \ --index-name ${'$'}ALGOLIA_INDEX_NAME \ --product ${'$'}CONFIG_JSON_PRODUCT \ --version ${'$'}CONFIG_JSON_VERSION \ --index-directory algolia-index/ \ 2>&1 | tee algolia-update-index-log.txtIn General Settings, in the Artifact path field, add algolia-update-index-log.txt to write logs.
In Dependencies, add artifacts produced by your help build configuration:
webhelp.zip
andalgolia-indexes-*.zip!** => algolia-index
. This action unpacks the ZIP archive with indexes to algolia-index.In Parameters, add the following environment variables:
- env.ALGOLIA_APP_NAME
Algolia application ID
- env.ALGOLIA_INDEX_NAME
Name of Algolia index
- env.ALGOLIA_KEY
Algolia Admin API Key.
This is a private key. Set the type of this parameter to
Password
, so that users without proper permissions will not see its value.- env.CONFIG_JSON_PRODUCT
Help instance ID from the tree file or the value of the
web-path
attribute specified in writerside.cfg if it is different from the ID- env.CONFIG_JSON_VERSION
Help instance version (usually the same as the branch name) specified in writerside.cfg
Save the build configuration settings and click Deploy. After it finishes successfully, go to the index in your Algolia account and make sure that the index records have really been uploaded.
In your repository on GitHub, go to New repository secret called
, and add aALGOLIA_KEY
with the Algolia Admin API Key from your Algolia account.Set up a GitHub Actions workflow that builds your help artifacts as described in Build and publish on GitHub. More specifically, make sure that you add a
publish-indexes
job to the workflow as described in Upload search indexes.
After you run this workflow successfully and the publish-indexes
job finishes, go to the index in your Algolia account and make sure that the index records have really been uploaded.
In your repository on GitLab, go to CI/CD Variable called
, and add a newALGOLIA_KEY
with the Algolia Admin API Key from your Algolia account.Set up a GitLab CI build pipeline that builds your help artifacts as described in Build and publish on GitLab. More specifically, make sure that you add a
publish-indexes
job to the workflow as described in Upload search indexes.
After you run this build pipeline successfully and the publish-indexes
stage finishes, go to the index in your Algolia account and make sure that the index records have really been uploaded.
After you upload the index records to Algolia, you can check that search works in your published help. You will need to upload new search index records every time you publish a new help build.