This is the first part of a three part series looking at the use of OpenSearch in combination with Ghost CMS.
Before you start
If you take a closer look at my website, you will see that I have implemented a full text search. Please use this as a demonstration.
It's a little hidden in the burger menu on the right side when you pop it up.
This tutorial is actually applicable to any theme. However, you will need server access to make changes. You also need a server on which you can install OpenSearch and Java. We will configure a webhook in the course of the tutorial, which I realized with Python3. Your ghost instance should be behind a reverse proxy. We also need to make adjustments to the reverse proxy, in my case NGINX.
If you want to do customizations, you need some knowledge of Handlebars and OpenSearch query syntax. But this is so minimal that it shouldn't stop you from continuing.
The structure consists of two webhooks: one for the search and one for the index. The index is rebuilt every time you change your website, which is very fast with OpenSearch.
Opensearch is the more open successor to Elasticsearch. The fork was created after unresolved licensing issues with Elasticsearch and is largely compatible with Elasticsearch.
OpenSearch cannot be installed as root. It is best to create an extra user for this. OpenSearch does not generally require Java, but it does for the initial configuration, e.g. to change the default password of the admin user.
Since I still have Elasticsearch listening on the default ports on my server, I need to change them. If you don't have Elasticsearch, you don't need to change the port to 9444 and 9555.
Change default password
When you run the command "opensearch-tar-install.sh" the admin user is created with the password admin. Of course we do not want that.
The password for admin resides hashed in the file:
To create a new password hash you need Java:
OpenSearch provides its own tool for creating the hash:
The environment variable JAVA_HOME must be mandatory set before!
Replace the old hash with any text editor with the new hash in the file "internal_users.yml".
For the changes to take effect, the server must be reconfigured using the securityadmin tool. A simple restart of OpenSearch is not sufficient:
The execution file is located in the OpenSearch root directory.
Test with Curl whether the password has really been changed:
NGINX configuration for webhooks
We need two webhooks. One webhook performs the search. The second one performs an indexing. Since the request should happen encrypted, we need the reverse proxy. As certificate you can use your Ghost CMS certificate. The webhooks will be /search and /buildindex.
Since we don't want any site to have access to your search, we restrict
Since only buildindex is really requested via GhostCMS webhooks, we can't introduce a restriction here due to problems with CORS. But we do this via the webhook script.
Prepare your Ghost instance
We need a content API key and also need to configure a webhook. Also, your theme needs to be customized on the front and back end.
Go to settings/integrations and add a new custom integration.
Copy the content API key and create a new webhook with event site changed. Target URL is your website/buildindex . You will need the key later.
Run it with a systemd unit file in /etc/systemd/system
Modify your Ghost CMS
Ghost CMS has a built-in search that is built into almost every theme. We need to replace this search.
Search for the button class gh-search
and replace it with
We just did the following: we created a listener that listens for clicks and enter input in the search box.
The handlebars script in the header is needed for the handlebars template of the search results.
Now create a new blank ghost cms page. In the opened tab for the page settings, select "Results" in the template field. If this entry does not appear, switch temporarily to another theme in the settings and back.