From 46b506d8c642fb887be75386ffaadabee8266cf0 Mon Sep 17 00:00:00 2001 From: Kian-Meng Ang Date: Sat, 30 Mar 2024 01:44:41 +0800 Subject: [PATCH] Revise instruction on running local Typesense instance We switch to Docker Compose for local Typesense setup and improves the documentation structure and clarity. --- .gitignore | 5 +- CHANGELOG.md | 10 +- LICENSE => LICENSE.md | 2 +- README.md | 104 +++++++++--------- docker-compose.yml | 17 +++ .../cheatsheet.cheatmd | 0 guides/running_local_typesense.md | 52 +++++++++ mix.exs | 8 +- 8 files changed, 136 insertions(+), 62 deletions(-) rename LICENSE => LICENSE.md (98%) create mode 100644 docker-compose.yml rename Cheatsheet.cheatmd => guides/cheatsheet.cheatmd (100%) create mode 100644 guides/running_local_typesense.md diff --git a/.gitignore b/.gitignore index 513f5a3..739532c 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,9 @@ ex_typesense-*.tar # Temporary files, for example, from tests. /tmp/ -.elixir_ls +# Typesense local dev data folder. +/typesense-data +# Misc. +.elixir_ls **.DS_Store diff --git a/CHANGELOG.md b/CHANGELOG.md index e563569..3c8a05b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + ## 0.3.5 (2023.08.13) * Fixed typos @@ -15,7 +20,6 @@ ## 0.3.2 (2023.07.11) * Maps struct pk to document's id - * Update http request timeout to `3,600` seconds ## 0.3.1 (2023.07.11) @@ -25,13 +29,9 @@ ## 0.3.0 (2023.06.20) * Fixed url request path for aliases - * Refactor functions inside collection and document. - * Changed return values from `{:ok, t()}` to `t()` only. - * Added cheatsheet section on docs - * Parse schema field types for `float`, `boolean`, `string`, `integer` and a list with these corresponding types. ## 0.2.2 (2023.01.26) diff --git a/LICENSE b/LICENSE.md similarity index 98% rename from LICENSE rename to LICENSE.md index 480f61d..435e6f3 100644 --- a/LICENSE +++ b/LICENSE.md @@ -1,4 +1,4 @@ -MIT License +# MIT License Copyright (c) 2021 Jaeyson Anthony Y. diff --git a/README.md b/README.md index 02e0c16..bc29be3 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Hex.pm](https://img.shields.io/hexpm/v/ex_typesense)](https://hex.pm/packages/ex_typesense) [![Hexdocs.pm](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ex_typesense) [![Hex.pm](https://img.shields.io/hexpm/l/ex_typesense)](LICENSE) -[![Typesense badge](https://img.shields.io/badge/Typesense-v0.25.1-darkblue)](https://typesense.org/docs/0.25.1/api) +[![Typesense badge](https://img.shields.io/badge/Typesense-v0.25.2-darkblue)](https://typesense.org/docs/0.25.2/api) Typesense client for Elixir with support for your Ecto schemas. @@ -17,68 +17,51 @@ Typesense client for Elixir with support for your Ecto schemas. ## Installation -If [available in Hex](https://hex.pm/docs/publish), the package can be installed -by adding `ex_typesense` to your list of dependencies in `mix.exs`: +ExTypesense requires Elixir `~> 1.14.x`. Read the [Changelog](CHANGELOG.md) for all available releases and requirements. This library is published to both [Hex.pm](https://hex.pm/ex_typesense) and [GitHub ](https://github.com/jaeyson/ex_typesense.git) repository. + +Add `:ex_typesense` to your list of dependencies in the Elixir project config file, `mix.exs`: ```elixir def deps do [ + # From default Hex package manager {:ex_typesense, "~> 0.3"} - ] -end -``` - -If you're adding this dep as a local path: -```elixir -def deps do - [ - {:ex_typesense, path: "/path/to/ex_typesense"} + # Or from GitHub repository, if you want to latest greatest from main branch + {:ex_typesense, git: "https://github.com/jaeyson/ex_typesense.git"} ] end ``` -then - -```bash -mix deps.compile ex_typesense --force -``` - ## Getting started -### 1. Spin up local typesense server - -```bash -mkdir /tmp/typesense-server-data -``` +### 1. Add credential to config -```bash -docker container run --rm -it -d \ - --name typesense \ - -e TYPESENSE_DATA_DIR=/data \ - -e TYPESENSE_API_KEY=xyz \ - -v /tmp/typesense-server-data:/data \ - -p 8108:8108 \ - docker.io/typesense/typesense:0.25.1 -``` +After you have setup a [local](./guides/running_local_typesense.md) Typesense or [Cloud hosted](https://cloud.typesense.org) instance, you can set the following config details to the config file: -### 2. Add creds to config +For local instance: -Config for setting up api key, host, etc. +```elixir +config :ex_typesense, + api_key: "xyz", + host: "localhost", + port: 8108, + scheme: "http" +``` -> You can also find api key and host in your dashboard if you're using [cloud-hosted](https://cloud.typesense.org) Typesense. +For Cloud hosted, you can generate and obtain the credentials from cluster instance admin interface: ```elixir config :ex_typesense, - api_key: "xyz", - host: "localhost", # "111222333aaabbbcc-9.x9.typesense.net" - port: 8108, # 443 - scheme: "http" # "https" - ``` + api_key: "credential", # Admin API key + host: "111222333aaabbbcc-9.x9.typesense.net" # Nodes + port: 443, + scheme: "https" +``` -### 3. Create a collection +### 2. Create a collection -#### using Ecto +#### Using Ecto In this example, we're adding `person_id` that points to the id of `persons` schema. @@ -121,13 +104,13 @@ defmodule Person do end ``` -next, create the collection from a module name +Next, create the collection from a module name. ```elixir ExTypesense.create_collection(Person) ``` -#### using maps +#### Using Maps ```elixir schema = %{ @@ -143,21 +126,21 @@ schema = %{ ExTypesense.create_collection(schema) ``` -### 4. Indexing documents +### 3. Indexing documents -#### 4.a via indexing multiple documents +For multiple documents: ```elixir Post |> Repo.all() |> ExTypesense.index_multiple_documents() ``` -#### 4.b or indexing single document +For single document: ```elixir Post |> Repo.get!(123) |> ExTypesense.create_document() ``` -### 5. Search +### 4. Search ```elixir params = %{q: "John Doe", query_by: "name"} @@ -166,8 +149,25 @@ ExTypesense.search(schema.name, params) ExTypesense.search(Person, params) ``` -Check [cheatsheet](https://hexdocs.pm/ex_typesense/cheatsheet.html) for more examples +Check [Cheatsheet](https://hexdocs.pm/ex_typesense/cheatsheet.html) for more examples. + +## License + +Copyright (c) 2021 Jaeyson Anthony Y. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. -Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc) -and published on [HexDocs](https://hexdocs.pm). Once published, the docs can -be found at . +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..baf1f9b --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,17 @@ +version: "3" +services: + typesense: + image: docker.io/typesense/typesense:0.25.2 + container_name: typesense + tty: true + restart: on-failure + environment: + - TYPESENSE_DATA_DIR=/data + - TYPESENSE_API_KEY=xyz + volumes: + - ./typesense-data:/data + ports: + # for internal status of the typesense server + - 8107:8107 + # for actual typesense server + - 8108:8108 diff --git a/Cheatsheet.cheatmd b/guides/cheatsheet.cheatmd similarity index 100% rename from Cheatsheet.cheatmd rename to guides/cheatsheet.cheatmd diff --git a/guides/running_local_typesense.md b/guides/running_local_typesense.md new file mode 100644 index 0000000..46122dc --- /dev/null +++ b/guides/running_local_typesense.md @@ -0,0 +1,52 @@ +# Running local Typesense + +This document guides you through setting up a local Typesense instance for +development purposes. Running a local instance allows you to experiment with +search functionalities and integrate them into your development workflow +seamlessly. + +## Prerequisites + +Before we begin, ensure you have the following installed on your development +machine: + +- Docker: - Docker provides a containerization platform + for running Typesense in an isolated environment. + +- Docker Compose: - Docker Compose + helps manage multi-container applications like Typesense. + + +## Setting up + +We are using Docker compose to bootstrap a local Typesense instance from a +sample `docker-compose.yml` file. + + +Clone the `ex_typesense` GitHub repository: + +```bash +git clone https://github.com/jaeyson/ex_typesense.git +``` + +Navigate to the cloned GitHub repository start the Typesense instance: + +```bash +cd ex_typesense +docker-compose up -d +``` + +Once you've started Typesense, you can verify its installation by accessing the +health endpoint through a browser or `curl` in the terminal: + +```bash +$ curl http://localhost:8108/health +{"ok":true} +``` + +In a separate terminal, you can view the logs of your local Typesense instance +using following command: + +```bash +docker-compose logs -f +``` diff --git a/mix.exs b/mix.exs index 3bd586f..c8e64a3 100644 --- a/mix.exs +++ b/mix.exs @@ -51,11 +51,13 @@ defmodule ExTypesense.MixProject do source_ref: "v#{@version}", source_url: @source_url, canonical: "https://hexdocs.pm/ex_typesense", + formatters: ["html"], extras: [ - "README.md", "CHANGELOG.md", - "LICENSE", - "Cheatsheet.cheatmd" + "README.md": [title: "Overview"], + "guides/running_local_typesense.md": [title: "Running local Typesense"], + "guides/cheatsheet.cheatmd": [title: "Cheatsheet"], + "LICENSE.md": [title: "License"] ] ] end