[Algoria] 30분만에 사용자가이드에 Algolia 적용하기(Docsearch)

♬ Algolia란?

- 웹 검색을 제공하는 SaaS 서비스 제품입니다.

(자세한 내용은 algolia 홈페이지에서 확인 가능합니다.)

www.algolia.com/doc/guides/getting-started/what-is-algolia/

What is Algolia?

 

---

♬ Algolia 적용하기

• 사용하게 된 배경 : 회사의 Guide 페이지에 검색 기능이 없어 저비용으로 적용하는 방법을 고안하다 Algolia를 도입하게 되면서 사용해 봤습니다. (antora라는 asciidoc을 build 하여 html로 만들어주는 모듈을 적용 검토하다가 antora guide페이지에서 Algolia를 사용하고 있다는 걸 알게 되었고 회사 서비스에 Algolia를 적용하기로 하였습니다.) 
• 선정 이유 : 다른 검색 서비스와 비교했을 때 구축 및 운영 관리가 쉽고 검색 페이지, 검색량이 적은 서비스에 Algolia가 적합하다고 판단하였습니다. 그리고 Analytics와 Monitoring메뉴를 통해 record, request개수, 검색량, 사용자수 등 통계지표도 제공해주어 여러 가지 용도로 활용할 수 있습니다. 
• 비용: 10 Unit( 1 Unit = 1000 search request and index capacity )까지 무료이고 그 이상부터는 유료입니다. 

<Algolia 적용 프로세스>

 

1. 가이드 문서 배포 : Jenkins를 통해 guide문서를 guide 서버에 배포합니다.
2. 가이드 문서 parsing : Docsearch를 이용하여 가이드 문서를 parsing 합니다.
3. algolia service로 data 인덱싱: parsing 한 데이터는 Docsearch에 의해 자동으로 algolia service에 인덱싱 됩니다.
4. 가이드 페이지에서 검색 : 검색 시 docsearch.js를 활용하여 algolia api를 호출
5. api호출에 대한 response: 검색 결과를 받아 화면에 노출

간단하게 설명하면 작업한 내용은 기존에 운영하던 Guide Page를

1) Docsearch를 이용하여 Parsing 하고 Algolia service에 인덱싱하여 저장하고
2) 저장된 데이터를 Docsearch.js를 활용하여 검색, 노출하는 작업을 진행

한 게 전부입니다.

♬ 그렇다면 Docsearch는 무엇인가?

문서 웹 사이트를 크롤링하고 해당 콘텐츠를 Algolia 색인으로 푸시하며
사용자가 관련 콘텐츠를 즉시 찾을 수 있도록 드롭 다운 검색 메뉴를 제공해주는 오픈소스 입니다.

html페이지를 parsing 해서 indexing 해주기 때문에 문서 검색용 검색 서비스에 적합합니다. 

(자세한 내용은 DocSearch 홈페이지에서 확인 가능합니다.)

docsearch.algolia.com/docs/what-is-docsearch

What is DocSearch? | DocSearch

 

♬ Docsearch 적용하기

docsearch.algolia.com/docs/run-your-own

Run your own | DocSearch

위에 공유한 URL에 들어가 보면 자세히 설명되어 있지만 다시 정리하여 보면 아래와 같습니다.

1. environment 설정하기

2. config.json 설정하기

3. 크롤링을 위한 Docker Image 실행하기 or 코드 기반으로 크롤링 실행하기

   Docker Image를 제공해주기 때문에 저는 Docker로 실행하였습니다.

4. 검색이 필요한 위치에 Docserch의 Dropdown-UI 적용하기

① environment 설정하기

DocSearch를 실행할 디렉터리로 이동하여 .env 파일을 만듭니다.

APPLICATION_ID={YOUR_APP_ID}
API_KEY={YOUR_API_KEY}

• APPLICATION_ID : Algolia의 Application ID
• API_KEY : Algolia 가입 후 발급받은 API key.(Admin api key입력)

② config.json 설정하기

{
  "index_name": "example",
  "start_urls": [
        "http://YOUR_DOC_URL"
  ],
  "selectors": {
    "lvl0": "FIXME h1",
    "lvl1": "FIXME h2",
    "lvl2": "FIXME h3",
    "lvl3": "FIXME h4",
    "lvl4": "FIXME h5",
    "lvl5": "FIXME h6",
    "text": "FIXME p, FIXME li"
  }
}

• index_name :  Algolia에 생성한 index_name
• start_urls: docSearch가 parsing 할 주소(여러 개 입력할 경우 , 로 구분하여 입력)
• selectors: html을 pasring 하기 때문에 html 파일의 selector의 정보를 입력

③ 위에 두 파일을 모두 설정하였으면 Docker Image를 실행

docker run -it --env-file=.env -e "CONFIG=$(cat /path/to/your/config.json | jq -r tostring)" algolia/docsearch-scraper

 

Docker Image를 실행하기 전 jq를 설치해야 합니다. jq는 command line에서 json을 컨트롤할 수 있는 도구입니다. 설치방법은 Google에게 물어보면 많은 설치 가이드가 있습니다.

Docker를 실행하고 나면 Agolia Index에 데이터가 인덱싱 되어 저장되는 걸 확인할 수 있습니다.

 

④ 검색이 필요한 위치에 Dropdown Search-UI 만들기

• </head> 태그 이전에 아래 코드 삽입
  {{docSearchJSVersion}}에는 버전 정보를 입력(저는 현재 최신 버전 2.6.3을 적용)

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@{{docSearchJSVersion}}/dist/cdn/docsearch.min.css"/>

 

•  </body> 태그 이전에 아래 코드 삽입

<script src="https://cdn.jsdelivr.net/npm/docsearch.js@{{docSearchJSVersion}}/dist/cdn/docsearch.min.js"></script>
<script>
  docsearch({
    // Your apiKey and indexName will be given to you once
    // we create your config
    apiKey: '<API_KEY>',
    indexName: '<INDEX_NAME>',
    //appId: '<APP_ID>', // Should be only included if you are running DocSearch on your own.
    // Replace inputSelector with a CSS selector
    // matching your search input
    inputSelector: '<YOUR_CSS_SELECTOR>',
    // Set debug to true to inspect the dropdown
    debug: false,
  });
</script>

 

• apiKey: Aloglia Api key입력(Search-Only Api key)
• indexName: 데이터를 저장한 Index name
• inputSelector: 검색용으로 만들어 놓은 input box의 id값

위 과정이 모두 완료되면 아래처럼 검색 시 Drowdown Search-UI가 보이게 됩니다!

---

♬ 테스트를 해보시고 궁금한 사항이 있으면 댓글 남겨주세요! ♬