Kong은 마이크로서비스 아키텍처에서 API 게이트웨이로 널리 사용되는 솔루션입니다. 그 중에서 개발자들이 Kong의 다양한 기능과 활용법을 쉽게 이해할 수 있도록 돕는 사이트가 바로 developer.konghq.com입니다. 오늘은 이 사이트의 소스 코드인 developer.konghq.com 프로젝트를 소개하고, 직접 로컬 환경에서 어떻게 실행해볼 수 있는지 알아보겠습니다.

Kong Developer Documentation 사이트 소개

Kong Developer Documentation 사이트는 Kong의 API 게이트웨이에 대한 문서를 제공하며, 이를 통해 개발자들이 Kong의 기능을 쉽게 이해하고 사용할 수 있도록 돕습니다. 이 사이트는 Ruby로 개발되어 있으며, 오픈소스 프로젝트로 GitHub에서 소스 코드를 확인할 수 있습니다. 이 프로젝트는 스타가 20개, 포크가 92개로 많은 개발자들이 관심을 가지고 있다는 점이 눈길을 끌고 있습니다. MIT 라이선스 하에 제공되므로, 자유롭게 수정하고 사용할 수 있습니다.

주요 기능과 특징

이 프로젝트는 다음과 같은 주요 기능과 특징을 가지고 있습니다.

  1. 문서화: Kong의 다양한 제품과 기능에 대한 상세한 문서를 제공합니다.
  2. 빠른 로컬 실행: 간단한 명령어로 로컬에서 문서 사이트를 실행할 수 있습니다.
  3. 부분 빌드: 전체 문서를 빌드할 필요 없이 특정 제품만 빠르게 빌드할 수 있는 기능을 제공합니다.
  4. 기여 가이드: 다른 개발자들이 문서에 기여할 수 있도록 가이드를 제공합니다.

    5. 로컬 환경에서 실행하기

    아래는 developer.konghq.com을 로컬 환경에서 실행하는 방법에 대한 단계별 가이드입니다.

    1. 환경 설정

    먼저, 이 프로젝트를 실행하기 위해 필요한 필수 요소들을 설치해야 합니다.

    • mise: mise 공식 사이트에서 설치 방법을 확인하세요.
    • libyaml: YAML 파일을 처리하기 위한 라이브러리입니다. libyaml GitHub 페이지에서 설치 안내를 참고할 수 있습니다.

      • 2. 코드 클론하기

      GitHub 레포지토리에서 소스 코드를 클론합니다.

      git clone https://github.com/Kong/developer.konghq.com.git
cd developer.konghq.com

      3. 의존성 설치하기

      의존성을 설치합니다.

      make install

      4. 환경 설정 파일 만들기

      .env.example 파일을 .env로 복사합니다. 이때, VITE_PORTAL_API_URL은 Kong이 제공하는 포털 URL에 맞춰 설정해야 합니다. 
      cp .env.example .env

      5. 사이트 실행하기

      사이트를 실행합니다.

      make run
      Server now ready on … 메시지가 나타나면, http://localhost:8888에서 문서 사이트를 확인할 수 있습니다.
      기본적으로 성능을 이유로 일부 페이지 생성이 생략됩니다. 전체 사이트를 로컬에서 생성하려면, 레포지토리의 루트에 있는 jekyll-dev.yml 파일에서 skip 섹션을 주석 처리해야 합니다.

      6. 특정 제품 빌드하기

      전체 문서 사이트를 빌드하는 데 시간이 걸릴 수 있습니다. 이럴 경우 특정 제품만 빌드할 수 있는데, KONG_PRODUCTS 환경 변수를 설정하면 됩니다. 예를 들어, AI Gateway 제품만 빌드하려면 다음과 같이 실행합니다.

      KONG_PRODUCTS=ai-gateway make run

      실무 활용 시나리오

      이 프로젝트는 API 게이트웨이를 사용하는 팀이나 개인에게 특히 유용합니다. 예를 들어, 새로운 API를 설계하고 문서화해야 할 때, developer.konghq.com을 로컬에서 실행하여 즉시 문서화된 내용을 확인하고 수정할 수 있습니다. 또한, 팀원들과의 협업을 위해 변경 사항을 쉽게 공유하고, 기여 가이드를 통해 다른 개발자들의 기여를 받는 것도 가능합니다.

      비슷한 도구와 비교

      Kong의 문서화 도구는 Jekyll 기반으로 되어 있습니다. 비슷한 도구로는 Read the Docs와 GitBook이 있습니다. Read the Docs는 자동화된 문서 생성과 호스팅을 제공하여 편리하지만, 설정 과정이 다소 복잡할 수 있습니다. GitBook은 직관적인 UI를 제공하나, 유료 플랜이 필요할 수 있습니다. 이에 비해 Kong의 문서화 도구는 오픈소스 특유의 자유로움과 커스터마이징 가능성을 제공합니다.

      추천 대상

    • Kong API 게이트웨이를 사용하는 개발자
    • 오픈소스 프로젝트에 기여하고 싶은 개발자
    • Ruby 및 Jekyll로 문서화 도구를 사용하고자 하는 팀

이 프로젝트를 통해 Kong의 다양한 기능을 더욱 쉽게 이해하고 활용할 수 있습니다. 여러분의 작업 환경에서 유용하게 사용해 보시기 바랍니다. 더 자세한 내용은 GitHub 레포지토리에서 확인할 수 있습니다.