그래서 Paperless-ngx에서 한글파일을 지원하도록 설정을 해 보았고, 이 글에서는 그 방법을 공유하고자 한다.
ChatGPT의 많은 도움을 받았다. ChatGPT에게 많은 영광을 돌린다.

사전 준비 사항

본 튜토리얼은 Paperless-ngx + Tika + Gotenberg의 Docker stack을 기준으로 설명한다.
해당 docker-compose.yml 파일은 Paperless-ngx 공식 레포지토리에서 확인할 수 있다: https://github.com/paperless-ngx/paperless-ngx/blob/main/docker/compose/docker-compose.postgres-tika.yml
(위 docker-compose.yml 파일은 PostgreSQL을 사용하지만 데이터베이스의 종류는 상관없다. SQLite를 사용해도 무방하다.)

본 튜토리얼은 Paperless-ngx 버전 v2.17.1을 기준으로 작성되었다.

1. Tika, Gotenberg 커스텀 이미지 작성하기

본 튜토리얼에서는 Tika와 Gotenberg의 도커 이미지를 약간 수정하여 사용한다.
말이 빌드이지 사실상 아주 가벼운 dependency 추가 정도만 하기 때문에, Raspberry Pi와 같은 저사양 머신에서도 충분히 빌드할 수 있다.
아래 두 dockerfile들을 각각 docker-compose.yml과 같은 폴더에 파일을 생성하여 저장한다.

tika.dockerfile

ARG TIKA_VERSION=3.2.0.0       # 필요하면 빌드 시 --build-arg 로 바꿀 수 있음

FROM apache/tika:${TIKA_VERSION} AS tika-hwp
ARG TIKA_VERSION
USER root

# 1) 다운로드 도구
RUN apt-get update -qq && \
    apt-get install -y --no-install-recommends curl

# 2) HWP parser JAR 추가
RUN mkdir -p /opt/tika-extra && \
    curl -L -o /opt/tika-extra/tika-parser-hwp-${TIKA_VERSION}.jar \
      https://repo1.maven.org/maven2/org/apache/tika/tika-parser-hwp/${TIKA_VERSION}/tika-parser-hwp-${TIKA_VERSION}.jar

# 3) tika-server 가 읽을 CLASSPATH 설정
ENV TIKA_CLASSPATH="/opt/tika-extra/*"

Tika는 제일 처음 문서를 업로드받았을 때, 문서에서 메타데이터와 텍스트를 추출하는 역할을 한다.
본 Dockerfile은 Apache Tika의 공식 이미지를 기반으로 하며, tika-parser-hwp JAR 파일을 추가하여 한글 파일(.hwp, .hwpx)을 처리할 수 있도록 한다.

gotenberg.dockerfile

ARG GOTENBERG_VERSION=8      # 필요하면 빌드 시 --build-arg 로 바꿀 수 있음

FROM gotenberg/gotenberg:${GOTENBERG_VERSION}
USER root

# 1) Java runtime + wget (unchanged)
RUN apt-get update -qq && \
    apt-get install -y --no-install-recommends openjdk-17-jre-headless 

# 2) LibreOffice Java bridge - make sure we pull it from backports
RUN echo "deb http://deb.debian.org/debian bookworm-backports main" \
       >> /etc/apt/sources.list && \
    apt-get update -qq && \
    apt-get install -y --no-install-recommends -t bookworm-backports \
        libreoffice-java-common

# 3) Register the H2Orestart filter
RUN wget -qO /tmp/H2Orestart.oxt \
        https://github.com/ebandal/H2Orestart/releases/download/v0.7.4/H2Orestart.oxt && \
    JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
    unopkg add --shared --suppress-license /tmp/H2Orestart.oxt 

RUN rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

USER gotenberg

Gotenberg는 문서 파일을 PDF로 변환하는 역할을 한다.
특히나 docx, odt 등의 파일을 변환하기 위해 LibreOffice를 사용하는데,
LibreOffice에서 hwp 및 hwpx 파일을 열 수 있는 Extension이 있다는 것에 영감을 받아, 기본 Gotenberg 이미지의 Libreoffice에 이 Extension을 설치하는 Dockerfile을 작성했다.
기본 Gotenberg 이미지에는 Libreoffice Java bridge가 포함되어 있지 않기 때문에, 이를 설치하는 약간 번거로운 작업이 필요하다.

2. Django 앱 작성

기본적으로 Paperless-ngx에서 문서를 업로드하면 document consumer가 파일 형식을 판별하여, 지원하지 않는 파일이면 먼저 오류를 띄워 버린다.
이를 수정하기 위해, HWP 파일을 정상적으로 받아들이도록 작은 Django 앱을 작성하여 Paperless-ngx에 등록한다.

docker-compose.yml이 있는 폴더에 hwp_tika라는 폴더를 생성하고, 그 안에 apps.py, __init__.py, signals.py 파일을 생성한다.
즉, 다음과 같은 구조가 된다:

.
├── docker-compose.yml
├── tika.dockerfile
├── gotenberg.dockerfile
└── hwp_tika
    ├── apps.py
    ├── __init__.py
    └── signals.py

apps.py, __init__.py, signals.py 파일의 내용은 다음과 같다:

# apps.py
from django.apps import AppConfig

class HwpTikaConfig(AppConfig):
    name = "hwp_tika"

    def ready(self):
        from documents.signals import document_consumer_declaration
        from .signals import hwp_consumer_declaration

        document_consumer_declaration.connect(hwp_consumer_declaration)

# __init__.py
default_app_config = "hwp_tika.apps.HwpTikaConfig"

# signals.py
from paperless_tika.parsers import TikaDocumentParser

def _get_parser(*args, **kwargs):
    return TikaDocumentParser(*args, **kwargs)

def hwp_consumer_declaration(sender, **kwargs):
    """
    Tell Paperless how to deal with Hangul Word Processor files.
    """
    return {
        "parser": _get_parser,
        "weight": 11,                    # >10 so it wins over the stock entry set
        "mime_types": {
            "application/x-hwp": ".hwp",
            "application/hwp":   ".hwp",
        },
    }

위 코드는 Paperless-ngx의 문서 consumer에 한글 파일을 처리할 수 있는 커스텀 consumer를 등록하는 역할을 한다.

3. Docker Compose 파일 및 환경변수 수정

이제 위에서 작성한 Tika, Gotenberg 이미지를 Paperless-ngx의 docker-compose.yml에 통합한다.
docker-compose.yml 파일을 열고, 다음과 같이 수정한다:

 gotenberg:
-    image: docker.io/gotenberg/gotenberg
+    build:
+        context: .
+        dockerfile: gotenberg.dockerfile

 tika:
-    image: docker.io/apache/tika
+    build:
+        context: .
+        dockerfile: tika.dockerfile

다음으로 환경변수를 수정하여 위에서 작성한 커스텀 Django 앱을 등록한다.
docker-compose.env 파일을 열고, 다음 줄을 추가한다 (혹은 docker-compose.yml 파일의 environment 섹션에 추가한다):

PAPERLESS_APPS=hwp_tika.apps.HwpTikaConfig

OIDC와 같이 다른 앱이 이미 등록되어 있었다면, 콤마(,)로 구분하여 추가한다.

4. 빌드 및 실행

이제 모든 준비가 끝났다. 다음 명령어로 Docker 이미지를 빌드하고 실행한다:

docker compose build
docker compose up -d

이제 Paperless-ngx가 실행되고, 한글 파일(.hwp, .hwpx)을 업로드할 수 있으며, 자동으로 PDF/A로 아카이빙된다.

그래서, Authentik의 OIDC provider를 마치 GitLab OAuth처럼 보이도록 설정하여 Mattermost와 연동하는 방법을 정리했다.
온라인에서 몇몇 자료를 찾을 수 있었지만, Mattermost와 Authentik 버전이 다 조금씩 달라서 설정에 어려움을 겪었다.

본 글에 나온 내용은 Mattermost 10.9.1 버전과 Authentik 2025.6.3 버전을 기준으로 작성되었다.
또한, 본 튜토리얼대로 하려면 Authentik 앞에 reverse proxy를 반드시 사용해야 한다. (path rewrite 때문)
참고로 우리 연구실의 Authentik은 Caddy v2 reverse proxy를 사용하고 있고, 본 튜토리얼도 이를 기준으로 작성되었다.
Traefik이나 Nginx 등 다른 reverse proxy를 사용한다면, 그에 맞춰 설정 파일을 변형하여 작성하길 바란다.

참고: 본 튜토리얼은 Authentik OAuth2 provider의 GitHub-compatible endpoint를 활용한다.

1. Authentik 설정

Application 생성

관리자 인터페이스에서, 좌측 사이드바의 “Applications” 메뉴를 클릭한 후, “Create” 버튼을 클릭한 후, 다음과 같이 입력한다:

• 이름: Mattermost
• 슬러그: mattermost

아래쪽의 “Create” 버튼을 클릭하여 Application 생성을 완료한다.

Provider 생성

다음으로, 좌측 사이드바의 “Providers” 메뉴를 클릭 -> “Create”를 클릭한다.

“OAuth2/OpenID Provider”를 선택하고 아래쪽의 “Finish” 버튼을 누른다.

다음 탭에서 다음 정보들을 입력하고 저장한다:

• 이름: Provider for Mattermost (혹은 임의의 이름)
• 인가 플로우: 임의로 설정. 저는 default-provider-authorization-explicit-consent (Authorize Application)로 설정했습니다
• 리디렉션 URI/Origin (정규표현식)
  • https://mattermost.my.domain/signup/gitlab/complete
  • https://mattermost.my.domain/login/gitlab/complete
  • mattermost.my.domain을 자신의 mattermost 서버 도메인으로 바꿔 입력한다.
• 고급 프로토콜 설정 > 스코프 (scopes) : 전부 다 빼도 된다. 왜냐하면 우리는 Authentik의 GitHub-compatible endpoint를 사용할 것이고 이에 따른 특별 scope들만 요청되기 때문이다.
• 클라이언트 ID와 클라이언트 비밀은 다음 단계에서 사용될 것이기 때문에 잘 기록해 둔다.

Application에 Provider 추가

다시 좌측의 Applications 메뉴 -> Mattermost 선택 -> 수정 -> Provider에 “Provider for Mattermost”를 선택한다.

2. Mattermost GitLab Auth 설정

Mattermost의 관리자 UI -> Authentication -> GitLab 메뉴로 들어간다.

• Enable authentication with GitLab: True
• Application ID: 1단계에서 기록한 클라이언트 ID
• Application Secret Key: 1단계에서 기록한 클라이언트 비밀
• GitLab Site URL: Authentik URL (예: https://sso.my.domain)

저장한다.

3. Reverse Proxy 설정

Authentik의 reverse proxy 설정파일을 수정하여, path rewrite 룰을 추가한다.

아래는 Caddy reverse proxy의 경우에 사용되는 Caddyfile의 예시이다:

sso.my.domain {
    uri replace /api/v4/user /user  1                         # User API Endpoint
    uri replace /oauth/authorize /login/oauth/authorize 1     # Auth Endpoint
    uri replace /oauth/token /login/oauth/access_token 1      # Token Endpoint
    uri replace /login/login/oauth /oauth 1
    reverse_proxy localhost:9000
}

4. Mattermost에서 GitLab OAuth로 로그인하기

기존 Mattermost 유저 여부에 따라서 로그인 방법이 달라진다.

기존 Mattermost 유저가 아닌 경우

Mattermost 로그인 페이지에서 “Log in with GitLab” 버튼을 클릭하여 Authentik 로그인 페이지로 이동한다.
Authentik에서 로그인한 후 (혹은 회원가입 후), Mattermost로 리디렉션된다. 이때 자동으로 Mattermost 계정이 생성된다.

기존 Mattermost 유저인 경우

대부분의 SSO를 지원하는 애플리케이션들의 경우 관리자가 일괄적으로 모든 유저들을 SSO로 전환할 수 있는 기능이 있지만… 킹받게도 Mattermost에는 그런 기능이 없다.
각 유저가 직접 프로필 설정에서 GitLab OAuth로 전환해야 한다.
다음은 내가 전환을 부탁하기 위해 랩 구성원들에게 보낸 메시지 내용이다. 이 내용을 참고해서 각 유저가 계정을 전환하면 된다:

1. Mattermost(PC)의 우측 최상단의 자신의 프로필 이미지 클릭 -> Profile
   • 데스크탑 앱 및 모바일 앱에서는 설정 불가, 반드시 PC 브라우저에서만 가능
2. 좌측 사이드바의 Security/보안 클릭
3. 우측 메뉴 맨 하단의 “Sign-in Method/접속 방식” 우측의 “Edit/편집” 클릭
4. “Switch to Using GitLab SSO” 클릭
5. 화면에서 시키는대로 현재 Mattermost 계정 비밀번호 입력하고 “Switch Account to Gitlab SSO” 클릭
6. SSO 사이트로 리다이렉트되면, 자신의 SSO 아이디/비밀번호로 로그인
7. 계정 전환이 완료되면, 이때부터는 Mattermost에서 “Log In with SSO”를 눌러서 로그인한다. (기존의 아이디, 비밀번호 사용 불가)

Tips

로그인 화면에서 GitLab 버튼 텍스트 변경하기 / 아이콘 숨기기

Mattermost 로그인 페이지에서 GitLab 로그인 버튼의 텍스트를 바꾸고 싶다면, Mattermost의 config.json 파일을 수정한다.
GitLabSettings.ButtonText 항목을 원하는 텍스트로 바꾸면 된다.
버튼 아이콘을 바꾸는 설정은 따로 없어서…. 나는 custom CSS를 이용하여 아이콘을 숨겼다.
Mattermost에는 custom CSS를 적용할 수 있는 기능이 없기 때문에 플러그인을 이용해야 한다. 나는 이 레포지토리에 있는 가이드를 가지고 플러그인을 생성했다.
적용한 CSS는 다음과 같다:

svg[aria-label="Gitlab Icon"] {
    display: none !important;
}

ID/Password 로그인 비활성화하기

모든 유저들이 전환을 완료했다면, Mattermost의 관리자 UI -> Authentication -> Email 메뉴로 들어가서 다음과 같이 설정한다:

• Enable account creation with email: False
• Enable sign-in with email: False
• Enable sign-in with username: False

마치며

뭔가 마무리를 해야 할 것 같은데 뭐라 써야 할지 잘 모르겠다.
앞으로도 연구실 서버 관리 일지를 비롯하여, 이 글과 같이 나만 알기엔 아까운 다양한 팁들을 정리해보려 한다.
끝.