Docs as code - (5) docusaurus on-premise 댓글 기능 추가 with comentario

 

 

 

Comentario 설정

comentario 서비스를 실행하기 위해서 docker-compose 파일과 secrets.yaml 파일의 설정이 필요합니다.

 

1. docker-compose.yml 파일 작성

version: '3'

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: comentario
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - shared-network

  app:
    container_name: comentario
    image: registry.gitlab.com/comentario/comentario
    environment:
      BASE_URL: http://localhost:8081/
      SECRETS_FILE: "/secrets.yaml"
      CORS_ALLOWED_ORIGINS: "*"
    ports:
      - "8081:80"
    volumes:
      - ./secrets.yaml:/secrets.yaml:ro
    networks:
      - shared-network

volumes:
  postgres_data:

networks:
  shared-network:
    external: true

 

2. secrets.yaml 파일 작성

postgres:
  host:     db
  port:     5432
  database: comentario
  username: postgres
  password: postgres

 

3. comentario 실행

docker-compose up -d

 

4. comentario 접속 후 domain 설정

회원 가입을 하면 아래와 같은 화면으로 들어갈 수 있습니다.

Domains에 들어가면 docusaurus 도메인을 추가할 수 있습니다.

저는 localhost로 테스트하기에 localhost:3000을 추가해줬습니다.

아래와 같이 추가합니다.

저장하고 이제 docusaurus에 스크립트를 추가하고 적용해보도록 합시다.

 

Docusaurus 설정

1. Docusaurus에 comentario용 plugin 설치

제가 직접 개발한 docusaurus plugin이 있어 이를 설치합니다.

npm install docusaurus-plugin-comentario-v3

2. Docusaurus에 comentario script 주소 연결하기

docusaurus.config.ts의 plugin에 아래 내용을 추가합니다.

server: 'comentario의 주소'를 추가하면 됩니다.

plugins: [
    [
      'docusaurus-plugin-comentario-v3',
      {
        server: 'http://localhost:8081',
      },
    ],
  ],

 

3. Docusaurus에 Footer를 comentario로 변경하기

comentario ui를 docusaurus에 적용하기 위해서 footer ui 코드를 변경해야합니다.

npm run swizzle @docusaurus/theme-classic Footer

swizzle을 하면 ui를 변경할 수 있는것 같아서 이 명령어를 입력합니다

그러면 theme/Footer 폴더가 생기는데 그 중에서 theme/Footer/index.tsx 파일을 아래와 같이 변경합니다.

import React, {useEffect, useState} from 'react';

import {useThemeConfig} from '@docusaurus/theme-common';
import {useLocation} from '@docusaurus/router';
import {useColorMode} from '@docusaurus/theme-common';

function Footer(): JSX.Element | null {
  const {footer} = useThemeConfig();
  const location = useLocation();
  const {colorMode, setColorMode} = useColorMode();
  const [pageId, setPageId] = useState(location.pathname); // Manage PageId state

  if (!footer) {
    return null;
  }
  const {copyright, links, logo, style} = footer;

  // 페이지 경로가 변경될 때 page-id 업데이트
  useEffect(() => {
    setPageId(location.pathname);
  }, [location.pathname]);

  // Set Comentario Theme mode based on colorMode of Docusaurus
  const comentarioTheme = colorMode === 'dark' ? 'dark' : 'light';
    return (
      <footer>
      <comentario-comments auto-init="true"
                           key={pageId} // Force re-render on page change
                           auto-non-interactive-sso="false"
                           lang="ko"
                           live-update="false"
                           max-level="5"
                           no-fonts="true"
                           page-id={pageId} // Set PageId
                           theme={comentarioTheme} // Set Comentario Theme
      ></comentario-comments>
      </footer>
  );
}

export default React.memo(Footer);

이제는 docusaurus를 실행하면 아래와 같이 comentario가 보이게 됩니다.

실제로 동작해보니 별도의 새로고침 없이 댓글에 대한 라이브 업데이트도 되어 좋은것 같습니다 ㅎㅎ 

댓글 기능이 잘 활성화 되도록 이용해봐야겠습니다.

 

해보면서 생긴 여러가지 문제들을 아래에 추가했습니다.

많은 도움되시길 바랍니다.

 

 

SSO (OIDC) 관련 시도했으나 정상 동작을 확인할 수 없었음.

Comentario의 로그인 동작 관련 해서 몇 가지 동작을 확인해봤었는데요.

사내에서 지원하는 SSO 로그인이 아래와 같이 2가지 정도 있었어서 이를 확인했었습니다.

1. Github Enterprise는 되는지 확인 할 것

2. Login via OIDC provider (with on-premise keycloak)

 

확인 결과는 둘 다 정상적으로 동작하지 않는것으로 확인되었습니다.

그래서 사내에서는 SSO는 없이 그냥 가입 없이 댓글을 쓰거나 회사 메일로 댓글을 쓰거나 두 가지로 해결하기로 했습니다.

 

 

이슈 1. 동작은 어느정도 하는것 같은데 CORS 문제가 발생함.

Access to XMLHttpRequest at 'http://localhost:8080/api/embed/comments' from origin 'http://localhost:3000' has been blocked by CORS policy: Method PUT is not allowed by Access-Control-Allow-Methods in preflight response.

cors 보내기 전에 보내는 메세지가 있는데 preflight 메세지라고 함.

이 메세지에 대한 method 종류가 allow 되어 있지 않아서 생긴 문제라고 함.

따라서, 이를 허용하는 코드를 넣어야함.

 

internal/api/restapi/configure_comentario.go · dev · comentario / Comentario · GitLab

internal/api/restapi/configure_comentario.go · dev · comentario / Comentario · GitLab

코드상에서는 cors handler라는게 있는데 뭐가 안되는건지 잘 모르겠네요.

 

(추가) 다시 확인해보니 내가 cors block/unblock하는 플러그인을 쓰고 있었습니다. 저도 까먹고 있었네요

cors block 상태로 되어있었던것이었네요

cors block을 없애니 정상 동작하는것을 확인했습니다.

 

이슈 2. footer를 페이지마다 다르게 하고싶습니다.

왜인지는 모르겠는데 항상 동일한 댓글이 보입니다.

pagd-id를 통해서 이를 해결한 줄 알았는데 아직 해결이 안된것같네요.

조금 더 확인해보니 다른 페이지로 넘어갈때 footer script가 새로고침이 안되어 문제가 발생하는것을 확인했습니다.

F5를 눌러서 새로고침을 하면 해당 페이지의 댓글창으로 전환이 되고 단순히 다른 문서 클릭으로는 새로고침이 안되어 생긴 문제였습니다.

 

이 부분은 리액트에서 useEffect를 통해서 지원할 수 있는 부분이라서 해당 코드를 수정하면 되었습니다.

commentario에 key라는 속성을 추가해서 페이지를 리렌더링 할 수 있었습니다.

리액트에서 DOM 업데이트를 최적화 하기 위해 사용하는 힌트라고하네요.

import React, {useEffect, useState} from 'react';

import {useThemeConfig} from '@docusaurus/theme-common';
import {useLocation} from '@docusaurus/router';
import {useColorMode} from '@docusaurus/theme-common';
import FooterLinks from '@theme/Footer/Links';
import FooterLogo from '@theme/Footer/Logo';
import FooterCopyright from '@theme/Footer/Copyright';
import FooterLayout from '@theme/Footer/Layout';

function Footer(): JSX.Element | null {
  const {footer} = useThemeConfig();
  const location = useLocation();
  const {colorMode, setColorMode} = useColorMode();
  const [pageId, setPageId] = useState(location.pathname); // Manage PageId state

  if (!footer) {
    return null;
  }
  const {copyright, links, logo, style} = footer;

  // 페이지 경로가 변경될 때 page-id 업데이트
  useEffect(() => {
    setPageId(location.pathname);
  }, [location.pathname]);

  // Set Comentario Theme mode based on colorMode of Docusaurus
  const comentarioTheme = colorMode === 'dark' ? 'dark' : 'light';
    return (
      <footer>
      <comentario-comments auto-init="true"
                           key={pageId} // Force re-render on page change
                           auto-non-interactive-sso="false"
                           lang="ko"
                           live-update="false"
                           max-level="5"
                           no-fonts="true"
                           page-id={pageId} // Set PageId
                           theme={comentarioTheme} // Set Comentario Theme
      ></comentario-comments>
      </footer>
  );
}

export default React.memo(Footer);

위 속성을 통해서 페이지 클릭시마다 별도의 새로고침 없이 매번 새로운 페이지의 댓글 리스트를 볼 수 있게되었습니다!

ADR 페이지

User Guide 페이지