Typesense Server

Typesense is an open source full-text search engine that returns results almost instantly and tolerates typos. This guide installs Typesense on a FlashPanel server and uses it to replace WordPress's default search, which is especially useful for websites with tens of thousands of posts or more.

Prerequisites

• A server connected to FlashPanel to install Typesense on
• A WordPress website (on the same server or another one)

INFO

A dedicated server for Typesense is recommended (it only also needs Nginx if you connect through a domain). You can still install it on the same server as your website, but keeping them separate reduces the load on the website server, and a problem on one side does not affect the other.

Step 1: Install Typesense

1. Go to the server management page, click the Apps menu and select the Not Installed tab
2. Find the Typesense application and click Install (the download icon)
3. In the dialog, check the Port (8108 by default) and the Master Key (randomly generated; you can replace it with your own value)
4. Note down the Port and Master Key, then click Install

TIP

If you forget the Master Key, go to the Installed tab of the Apps page, click Config for Typesense and look for the api-key value. The sections below use the default port 8108; if you changed it, use your port instead.

Step 2: Allow the Website to Connect to Typesense

Choose the option that matches where your website runs:

• Website and Typesense on the same server: nothing else to do; the website connects through 127.0.0.1:8108.
• Different servers, connecting by IP and port: on the Typesense server, add a firewall rule that Allows port 8108, and enter the website server's IP in From IP Address so only that server can connect. Note that this connection is not encrypted.
• Different servers, connecting through a domain (recommended): on the Typesense server, create a new website with a Domain Name (for example search.domain.com, with DNS pointed to the server) and Proxy Port 8108, then install SSL for it. The connection is encrypted over HTTPS and port 8108 does not need to be opened.

Step 3: Create API Keys

Your website needs an API key to connect to Typesense. You could use the Master Key, but it is not recommended because that key has full access. Instead, create two scoped keys:

• Admin API Key: used to index data
• Search Only API Key: used only for searching, safe to expose to visitors' browsers

Open Terminal on the Typesense server's overview page and run the commands below. Replace abcxyz with your Master Key:

# Master Key
TYPESENSE_API_KEY=abcxyz

# Create Admin API Key
curl 'http://localhost:8108/keys' \
    -X POST \
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"description":"Admin Key","actions": ["*"], "collections": ["*"]}'

# Create Search Only API Key
curl 'http://localhost:8108/keys' \
    -X POST \
    -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"description":"Search-only key","actions": ["documents:search"], "collections": ["*"]}'

Each command returns a JSON object; the value of its value field is the API key. Save it right away, because Typesense shows this value only once.

Step 4: Connect from WordPress

1. In the WordPress admin, install and activate the Search with Typesense plugin (free; WooCommerce support requires a paid add-on)
2. Open the plugin's settings page and select the General tab
3. Fill in the fields according to the option you chose in step 2:

Field	Same server	Different server, by IP	Different server, by domain
PROTOCOL	http	http	https
ENTER NODE URI	127.0.0.1	Typesense server IP	search.domain.com
ENTER PORT	8108	8108	443

4. Enter the Admin API Key in ADMIN API KEY and the Search Only API Key in SEARCH API KEY (see step 3)
5. Click Save. If the connection works, the plugin shows a success notification in the corner of the screen

Step 5: Index Data and Replace the Search Box

1. Open the plugin's Search Configuration tab
2. In Select Posts Types to Enable, choose the content types to search (for example Posts, Category)
3. Click Index for each content type and wait until it finishes. Do not leave the page while indexing. For large amounts of data, index with WP-CLI by following the plugin's guide
4. Turn on Replace WordPress Search to replace WordPress's default search box, then choose Replace with Instant Search (a results page with filters) or Replace with Autocomplete (suggestions while typing)

If you want a dedicated search page, create a blank page in WordPress and insert the plugin's shortcode (see the shortcode documentation).

Verify the Result

1. In the Typesense server's Terminal, run curl http://localhost:8108/health. The result {"ok":true} means Typesense is running
2. Open your WordPress website, type a keyword into the search box and check that results come from Typesense

Troubleshooting

• The plugin cannot connect: double-check PROTOCOL, ENTER NODE URI and ENTER PORT. When connecting by IP, make sure port 8108 is open for the website server's IP; when connecting through a domain, make sure the website has SSL
• Forbidden - a valid x-typesense-api-key header must be sent error: the API key is wrong or has been deleted. Create a new key as in step 3
• Typesense is not running: on the Installed tab of the Apps page, click Log for Typesense to see the error, then click Restart