Basic Meilisearch Setup With Authentication On A Mac
The official quick start for Meilisearch doesn't include authentication. This post is a version of the quick start with authentication included. The details are for running on a mac and storing keys in the default macOS Keychain Access app for programmatic access. Other systems (or using plain text) for storing and uses the keys could be substituted as well.
Install Meilisearch
Install the Meilisearch software via Homebrew with:
brew update && brew install meilisearch
(There are other installation options as well)
Create A Root Key
Create a new key in Keychain Access with a good random key value that will be used for the top level root key. (I use a space in front of commands that contain passwords and keys to keep them out of my command history via this setting in zsh)
security add-generic-password -a YOUR_USERNAME -s meilisearch--root-key -w SOME_GOOD_KEY
Note: The Meilisearch documentation calls the key a master key. I use the term 'root' instead
Create A Startup Script
To make it easier to start meilisearch with the main/master key and some other params, I use this script named meilisearch-startup.bash
#!/bin/bash
export MEILI_MASTER_KEY=$(security find-generic-password -w -a YOUR_USERNAME -s meilisearch--root-key)
export MEILI_HTTP_ADDR=127.0.0.1:7700
export MEILI_ENV=development
export MEILI_DB_PATH=./data-ms
export MEILI_NO_ANALYTICS=true
meilisearch
Change permissions on the script to make it executable:
chmod u+x meilisearch-startup.bash
Then, run the script in the terminal with this command (NOTE: The first time you run this you'll be asked for your for your main user account password one or two times. Enter it and click 'Always Allow' so you don't have to enter it every time)
./meilisearch-startup.bash
The server will startup and show a basic splash screen in the terminal window
Get Search and Admin API Keys
The Main/Master key you created above and used to start the server should not be used for anything other than getting the two keys that will be used to run and query the system.
Those keys are the Search Key which is a public key. And, the Admin Key which should be kept private and only used internally to manage the Meilisearch server and indexes
The terminal command to get the Search and Admin keys is:
curl \
-X GET 'http://127.0.0.1:7700/keys' \
-H "Authorization: Bearer $(security find-generic-password -w -a YOUR_USERNAME -s meilisearch--root-key)"
That command will return a JSON response that looks like:
{
"results": [
{
"description": "Default Search API Key (Use it to search from the frontend)",
"key": "RANDOM_SEARCH_KEY_VALUE",
"actions": [
"search"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2022-05-22T17:35:31.190234Z",
"updatedAt": "2022-05-22T17:35:31.190234Z"
},
{
"description": "Default Admin API Key (Use it for all other operations. Caution! Do not use it on a public frontend)",
"key": "RANDOM_ADMIN_KEY_VALUE",
"actions": [
"*"
],
"indexes": [
"*"
],
"expiresAt": null,
"createdAt": "2022-05-22T17:35:31.190015Z",
"updatedAt": "2022-05-22T17:35:31.190015Z"
}
]
}
Grab the RANDOM_SEARCH_KEY_VALUE
and RANDOM_ADMIN_KEY_VALUE
and add them to Keychain Access with:
security add-generic-password -a YOUR_USERNAME -s meilisearch--search-key -w RANDOM_SEARCH_KEY_VALUE_FROM_JSON
and
security add-generic-password -a YOUR_USERNAME -s meilisearch--admin-key -w RANDOM_ADMIN_KEY_VALUE_FROM_JSON
Create An Index Via JSON
Indexes can be created manually or automatically by uploading documents (which are the things to search). Following the same format at the official quick start, we'll do the latter.
Download this sample file: movies.json
You can get it with this command:
curl https://docs.meilisearch.com/movies.json --output movies.json
The structure of the movies.json
file is an array of objects that look like:
{
"id": "287947",
"title": "Shazam!",
"poster": "https://image.tmdb.org/t/p/w500/xnopI5Xtky18MPhK40cZAGAOVeV.jpg",
"overview": "A boy is given the ability to become an adult superhero in times of need with a single magic word.",
"release_date": 1553299200,
"genres": ["Action", "Comedy", "Fantasy"]
}
Add the data to Meilisearch (and implicitly create the index) with this command:
curl \
-X POST 'http://127.0.0.1:7700/indexes/movies/documents' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $(security find-generic-password -w -a YOUR_USERNAME -s meilisearch--admin-key)" \
--data-binary @movies.json
(The name of the index will be movies
since the url path started with indexes/movies
)
Meilisearch handles adding the documents asynchronously in the background. Check the status with:
curl \
-H "Authorization: Bearer $(security find-generic-password -w -a YOUR_USERNAME -s meilisearch--admin-key)" \
-X GET 'http://localhost:7700/indexes/movies/tasks/0'
Everything is ready when you see "status":"succeeded"
in the response.
Searching Via Website
Now that the index is setup and populated you can access the local web page to search.
Go to: http://localhost:7700 and enter your admin API Key.
If you don't still have the JSON up with the Admin Key, you can get it inside the Keychain Access GUI app by searching for meilisearch, or use this command to get it:
security find-generic-password -w -a YOUR_USERNAME -s meilisearch--admin-key
Play around with the search to see how fast it is with the 19K+ movies
Searching Programatically
Programatic searches use the Search Key. A curl command to run a search looks like this:
curl \
-X POST 'http://127.0.0.1:7700/indexes/movies/search' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $(security find-generic-password -w -a YOUR_USERNAME -s meilisearch--search-key)" \
--data-binary '{ "q": "botman" }'
Running that will return a JSON response with details on all the hits.
Next Steps
That has the basics up and running. For the next step, check out the Official Meilisearch 101 Documentation. You can also check out all the official SDKs the Meilisearch offers for integration.
It still blows me away that something this fast and powerful is open source. Kudos to the folks how made and maintain it.