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

ADR 도입기 - (3) Docs as code 추가 기능 도입 (Local LLM으로 문서 번역, 문서 페이지 접속 데이터)

Analytics 관련 몇가지 자료를 더 찾아보다가 드디어 API를 사용하지 않고도 On-premise로 Docusaurus에 대해서 접속 정보를 확인할 수 있는 페이지를 찾았습니다.

 

여러모로 Docusaurus와의 연결성과 배포의 용이성을 판단 해 봤을때 대략 사용 가능한 후보는 두개정도 있었는데요.

1. matomo

2. ackee 

였습니다.

ackee의 경우에는 여러가지를 시도 해 봤을때 plugin들이 정상적으로 동작하지 않아서 우선은 보류해두고 matomo를 연결하는 방법을 정리 해 봤습니다.

 

요약하자면 현재 On-premise Analytics로 사용할 수 있는 오픈소스는 Matomo뿐입니다.

 

1. Matomo 설치

아래 링크를 참조했습니다.

Hosting Matomo with Docker Compose: A Step-by-Step Guide

 

1) db.env 생성하기

MYSQL_PASSWORD=matomo
MYSQL_DATABASE=matomo
MYSQL_USER=matomo
MATOMO_DATABASE_ADAPTER=mysql
MATOMO_DATABASE_TABLES_PREFIX=matomo_
MATOMO_DATABASE_USERNAME=matomo
MATOMO_DATABASE_PASSWORD=matomo
MATOMO_DATABASE_DBNAME=matomo

 

2) docker-compose.yml 생성하기

version: "3"

services:
  db:
    image: mariadb:lts
    command: --max-allowed-packet=64MB
    restart: always
    volumes:
      - db:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=rootpw
    env_file:
      - ./db.env

  app:
    image: matomo:fpm-alpine
    restart: always
    links:
      - db
    volumes:
      - matomo:/var/www/html
    environment:
      - MATOMO_DATABASE_HOST=db
      - PHP_MEMORY_LIMIT=2048M
    env_file:
      - ./db.env

  web:
    image: nginx:alpine
    restart: always
    volumes:
      - matomo:/var/www/html:ro
      - ./matomo.conf:/etc/nginx/conf.d/default.conf:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8085"]
      interval: 1m
      timeout: 10s
      retries: 3
    ports:
      - 8085:80

volumes:
  db:
  matomo:

 

3) matomo.conf 생성하기

아래는 http를 사용하는 경우입니다.

upstream php-handler {
  server app:9000;
}

server {
  listen 80;
  client_header_timeout 1000000;
  client_body_timeout 1000000;
  send_timeout 1000000;
  fastcgi_read_timeout 1000000;

  add_header Referrer-Policy origin;
  root /var/www/html;
  index index.php;
  try_files $uri $uri/ =404;

  location ~ ^/(index|matomo|piwik|js/index|plugins/HeatmapSessionRecording/configs).php {
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    try_files $fastcgi_script_name =404;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_param HTTP_PROXY "";
    fastcgi_pass php-handler;
  }

  location ~* ^.+\.php$ {
    deny all;
    return 403;
  }

  location ~ /(config|tmp|core|lang) {
    deny all;
    return 403;
  }

  location ~ /\.ht {
    deny all;
    return 403;
  }

  location ~ js/container_.*_preview\.js$ {
    expires off;
    add_header Cache-Control 'private, no-cache, no-store';
  }

  location ~ \.(gif|ico|jpg|png|svg|js|css|htm|html|mp3|mp4|wav|ogg|avi|ttf|eot|woff|woff2|json)$ {
    allow all;
    expires 1h;
    add_header Pragma public;
    add_header Cache-Control "public";
  }

  location ~ /(libs|vendor|plugins|misc/user) {
    deny all;
    return 403;
  }

  location ~/(.*\.md|LEGALNOTICE|LICENSE) {
    default_type text/plain;
  }
}

 

하나의 폴더에 위의 파일을 모두 넣어두고 아래 명령어를 실행해서 matomo를 실행할 수 있습니다.

docker-compose up

 

2. Matomo 웹사이트 실행

localhost:8085 를 통해서 matomo에 접속합니다.

아래와 같은 설정 화면이 나옵니다.

계속 다음을 넘겨주다가 슈퍼유저 설정을 본인이 원하는 계정으로 설정합니다.

저의 경우 우선은 테스트를 위해서 admin/password로 설정했습니다.

이메일은 본인걸 넣어도 되고, 아무 이메일을 넣어도 동작합니다.

 

웹사이트 페이지에서 본인이 설정할 페이지 주소를 입력합니다.

저는 localhost를 통해서 docusaurus를 배포 예정입니다.

docker를 사용하는 경우 http://host.docker.internal 을 입력합니다.

docusaurus의 기본 사용 port가 3000인데 80번 포트로 실행 할 예정입니다.

마지막 페이지인데 docusaurus의 추적 코드를 넣는 곳입니다.

우리의 경우 docusaurus의 matomo plugin을 활용할 예정이므로 무시하고 다음으로 넘어갑니다.

마지막 페이지에서도 계속하기를 눌러서 설정을 완료합니다.

설정이 완료되면 로그인페이지가 뜨며 로그인 하면 됩니다.

이제는 docusaurus를 설정해야합니다.

 

2. Docusaurus matomo plugin 설치하기

karser/docusaurus-plugin-matomo: Matomo plugin for Docusaurus v2/v3

GitHub - karser/docusaurus-plugin-matomo: Matomo plugin for Docusaurus v2/v3

 

Docusaurus와 matomo를 쉽게 연결하기 위해서 docusaurus-plugin-matomo를 설치합니다.

아래 명령어를 통해서 설치할 수 있습니다.

Docusaurus 소스코드 폴더에서 npm install로 설치하도록 합니다.

npm install --save docusaurus-plugin-matomo

 

 

3. Docusaurus.config.ts (js) 에 plugin 설정 추가하기

docusaurus.config.ts에 아래와 같이 추가합니다.

현재는 matomo 실행 위치를 localhost:8085로 설정할 예정이기에 matomo url을 8085로 설정합니다.

themes: [
    // ... Your other themes.
    'docusaurus-plugin-matomo',
  ],

themeConfig: {
    matomo: {
      matomoUrl: 'http://localhost:8085/',
      siteId: '1',
      phpLoader: 'matomo.php',
      jsLoader: 'matomo.js',
    },
  }

이제 설정이 완료되었습니다.

 

4. Docusaurus 실행하기

아래 명령어를 통해서 Docusaurus를 실행합니다.

$ npm run serve -- --build --port=80 --host=host.docker.internal

실행 후 docusaurus 웹 페이지들을 돌아다니면서 접속해보고 matomo 사이트를 확인해봅시다.

 

5. Matomo 대시보드 확인하기

localhost:8085를 접속해보면 대시보드가 업데이트 되어있음을 확인할 수 있습니다.

유저가 어떤 플랫폼을 사용하고 어떤 페이지를 들어갔는지를 바로 확인할 수 있습니다.

Funnels 아래 부터는 구매를 해야하는 기능들이라서 활용하기는 힘들지만

접속 정보/페이지를 지속적으로 확인하는데에는 사용하기 쉬운 오픈소스임을 알 수 있었습니다.

Docs as code 페이지에서 활용하여 사용자들이 docs as code를 좀 더 잘 활용할 수 있도록 analytics를 활용할 수 있을것 같습니다.

 

추가 - HTTPS로 matomo 실행하기

https로 matomo를 실행하기 위해서는 설정 파일들을 일부 변경해야하고 인증서도 추가해야합니다.

우선 localhost를 https로 동작시키게 하기 위해서 인증서를 생성해보겠습니다.

 

1. Localhost를 https로 통신하기 위한 인증서 생성

certs 폴더를 생성합니다.

mkdir certs
cd certs

 

 

localhost를 위한 인증서를 해당 폴더에 생성합니다.

2. Generate a Private Key and a Certificate Signing Request (CSR)

openssl req -new -newkey rsa:2048 -nodes -keyout localhost.key -out localhost.csr

 

3. Generate a Self-Signed Certificate

openssl x509 -req -days 365 -in localhost.csr -signkey localhost.key -out localhost.crt

 

4. docker-compose.yml 파일 수정

version: "3"

services:
  db:
    image: mariadb:lts
    command: --max-allowed-packet=64MB
    restart: always
    volumes:
      - db:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=rootpw
    env_file:
      - ./db.env

  app:
    image: matomo:fpm-alpine
    restart: always
    links:
      - db
    volumes:
      - matomo:/var/www/html
    environment:
      - MATOMO_DATABASE_HOST=db
      - PHP_MEMORY_LIMIT=2048M
    env_file:
      - ./db.env

  web:
    image: nginx:alpine
    restart: always
    volumes:
      - matomo:/var/www/html:ro
      - ./matomo.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8085"]
      interval: 1m
      timeout: 10s
      retries: 3
    ports:
      - 8085:80
      - 443:443

volumes:
  db:
  matomo:

 

5. matomo.conf 파일 수정

upstream php-handler {
  server app:9000;
}

server {
  listen 80;
  server_name localhost;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl;
  server_name localhost;

  ssl_certificate /etc/nginx/certs/localhost.crt;
  ssl_certificate_key /etc/nginx/certs/localhost.key;

  client_header_timeout 1000000;
  client_body_timeout 1000000;
  send_timeout 1000000;
  fastcgi_read_timeout 1000000;

  add_header Referrer-Policy origin;
  root /var/www/html;
  index index.php;
  try_files $uri $uri/ =404;

  location ~ ^/(index|matomo|piwik|js/index|plugins/HeatmapSessionRecording/configs).php {
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    try_files $fastcgi_script_name =404;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_param HTTP_PROXY "";
    fastcgi_pass php-handler;
  }

  location ~* ^.+\.php$ {
    deny all;
    return 403;
  }

  location ~ /(config|tmp|core|lang) {
    deny all;
    return 403;
  }

  location ~ /\.ht {
    deny all;
    return 403;
  }

  location ~ js/container_.*_preview\.js$ {
    expires off;
    add_header Cache-Control 'private, no-cache, no-store';
  }

  location ~ \.(gif|ico|jpg|png|svg|js|css|htm|html|mp3|mp4|wav|ogg|avi|ttf|eot|woff|woff2|json)$ {
    allow all;
    expires 1h;
    add_header Pragma public;
    add_header Cache-Control "public";
  }

  location ~ /(libs|vendor|plugins|misc/user) {
    deny all;
    return 403;
  }

  location ~/(.*\.md|LEGALNOTICE|LICENSE) {
    default_type text/plain;
  }
}

 

6. docusaurus.config.ts 파일을 https로 수정

http로 되어있던 matomo의 themeConfig 파일을 https로 수정하고 포트도 8508에서 443으로 수정합니다.

themeConfig: {
    matomo: {
      matomoUrl: 'https://localhost:443/',
      siteId: '1',
      phpLoader: 'matomo.php',
      jsLoader: 'matomo.js',
    },
}