Docs as code - (4) Docusaurus 방문자 확인 on-premise ackee analytics 적용기

Docs as code - (1) Docusaurus v3의 on-premise analytics (matomo) 설정하기 (https 설정 추가)

Docs as code - (1) Docusaurus v3의 on-premise analytics (matomo) 설정하기 (https 설정 추가)

위의 포스트에서 matomo analytics를 적용을 해 보았습니다.

정상 작동하는 것을 확인은 했으나 일단 matomo analytics가 안예뻐서 ackee를 한번 동작시켜보고자 하는 마음이 있어서 이 포스트를 통해서 진행해보려고합니다.

Self-hosted website analytics | Ackee

Self-hosted website analytics | Ackee

ackee 웹사이트 예시

 

우선은 기존에 ackee + docusaurus를 결합한 플러그인이 있나 확인 해 봤을때 아래와 같은 플러그인이 존재했습니다.

다만, docusaurus v3부터 지원이 되지 않는 듯 했습니다.

docusaurus-plugin-ackee-improved

위의 플러그인을 통해서는 ackee가 정상 작동하지 않는 문제가 있어서 해당 프로젝트를 fork 하여 docusaurus v3에 맞게 수정해보려고 했습니다.

현재 저의 Docusaurus 버전은 v3.5.2를 사용하고 있습니다.

ackee는 3.4.2 버전을 사용합니다.

 

또한, 맥 환경에서 테스트했음을 알려드립니다. 

(추가) 윈도우 환경에서도 정상 동작을 하는것으로 확인했습니다.

 

Docusaurus + ackee 적용하기

1. ackee 실행하기

ackee는 docker-compose를 이용해서 쉽게 실행을 할 수 있습니다.

docker-compose.yml 파일과 .env 파일을 두개 생성하여 실행하도록 합니다.

version: "2"
services:
  ackee:
    image: electerious/ackee
    container_name: ackee
    restart: always
    ports:
      - "3000:3000"
    environment:
      - WAIT_HOSTS=mongo:27017
      - ACKEE_MONGODB=mongodb://mongo:27017/ackee
    env_file:
      - .env
    depends_on:
      - mongo
  mongo:
    image: mongo
    container_name: mongo
    restart: always
    volumes:
      - ./data:/data/db

아래는 .env 파일입니다.

username과 password 그리고 allow_origin 값을 포함하고 있습니다.

ACKEE_USERNAME=username
ACKEE_PASSWORD=password
ACKEE_ALLOW_ORIGIN=*
NODE_ENV=development

아래 명령어로 ackee프로그램을 실행합니다.

docker-compose up -d

 

 

2. ackee의 domain ID 발급하기

localhost:3000으로 실행했으므로 해당 사이트로 접속합니다.

위에서 정한 username/password를 입력하고 아래와 같이 New domain을 클릭하여 domain ID를 발급받습니다.

저의 경우 미리 만들어둔 docusaurus 이름의 domain ID를 사용합니다.

(805d4e27로 시작하는 숫자 + 문자 조합이 domain ID입니다.)

 

3. docusaurus-plugin-ackee-v3 플러그인 설치

제가 docusaurus v3 버전에 맞게 일부 수정해서 만든 npm 프로그램을 설치합니다.

docusaurus-plugin-ackee-v3 - npm

docusaurus-plugin-ackee-v3

npm install docusaurus-plugin-ackee-v3

 

4. docusaurus.config.js에 docusaurus-plugin-ackee-v3 플러그인 내용 추가하기

그리고 docusaurus-plugin-ackee-v3에 맞게 config 파일에 ackee 설정 내용들을 추가합니다.

plugins에 ackee 설정 내용을 추가합니다.

domainID는 2번에서 발급받은 domain ID를 사용합니다.

plugins: [
    [
      'docusaurus-plugin-ackee-v3',
      {
        // Ackee domain ID
        domainId: '805d4e27-ca1d-4cde-9d8c-c4e3ecbdb376',

        // URL to your Ackee server
        // MUST NOT END WITH SLASH ('/')
        server: 'http://localhost:3000',

        // Enable or disable tracking of personal data (OS, device, browser, screen size, user language)
        detailed: true,

        // Enable or disable tracking when on localhost
        ignoreLocalhost: false,

        // Enable or disable the tracking of your own visits
        // Enabled by default, should be turned off when using a wildcard Access-Control-Allow-Origin header
        // Some browsers may strictly block third-party cookies and this option will have no impact in this situation
        ignoreOwnVisits: false,
      },
    ],
  ]

이를 적용하고 아래 명령어를 통해서 docusaurus 사이트를 실행합니다.

npm run serve -- --build --port=80 --host=0.0.0.0

5. docusaurus에 접근해보고 ackee에 잘 반영되는지 확인해보기

docusaurus 페이지를 접근해보고 ackee 배포 사이트에서 이를 확인해 보면 analytics가 잘 반영되는 모습을 볼 수 있습니다.

2개의 브라우저에서 동시에 Docusaurus 페이지에 접근하고 있는 모습 : active visitors가 2로 되어있음

safari 및 chrome 브라우저에서 접속하는게 잘 tracking 되는 모습

 

이슈 트래킹

1. 윈도우에서는 동일한 과정을 거쳤을 때 정상 동작하지 않는 문제가 있음.

웹 콘솔에서 정상적인 localhost/host.docker.internal 도메인을 줬음에도 unknown domain이 발생하는 현상이 있습니다.

정확한 원인을 파악하면 수정사항과 함께 업데이트 하도록 하겠습니다.

(추가) 원인은 어처구니 없는 실수였습니다..

docusaurus.config.js에 domain ID가 아니라 permanent token 을 집어넣어서 원하는 domain을 찾지 못하는 문제였습니다.

Domain ID가 아닌 permanent token을 사용해서 문제였습니다..

이를 고쳐주고 나니 아래와 같이 unknown domain 오류가 발생 하지 않고

unknown domain이 뜨지 않는 모습

 

windows의 ackee에서도 정상적으로 analytics tracking이 가능한 모습을 볼 수 있었습니다.