ZimaOS 앱 스토어에서 진행한 Paperless-ngx 설치는 마지막 단계에서 실패했습니다. 처음에는 GitHub Container Registry에서 Tika 이미지를 가져오는 중 인증되지 않음 오류가 발생했고, 이후에는 레지스트리 미러의 DNS 조회 실패가 발생했습니다. 이 조합은 이 문제를 단순히 “Paperless가 고장 났다”라고 보기 어렵게 만듭니다. 실패한 구성 요소는 선택 사항인 Tika 서비스/이미지 경로였고, 시도할 때마다 레지스트리 엔드포인트 자체도 달라졌습니다.
공개 스레드에서는 ZimaOS 앱 스토어의 문제가 해결되었다는 확인까지 이르지 못했습니다. 한 사용자는 Tika 이미지를 Apache 이미지로 변경해 설치를 100%까지 진행했지만, 스택은 여전히 실행되지 않았습니다. 현재 Paperless-ngx 문서에서는 더 명확한 방법을 제공합니다. 유지 관리되는 Docker Compose 템플릿을 사용하고, 해당 문서 형식이 필요한 경우에만 Tika/Gotenberg 변형을 활성화하는 방식입니다.
첫 번째 실패는 GHCR 인증 오류였습니다
원래 오류는 약 80% 지점에서 발생했습니다.
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorized로컬 Docker 이미지를 삭제하고 다시 설치해도 결과가 달라지지 않았으므로, 단순히 오래된 로컬 이미지가 원인이라고 보기는 어렵습니다.
다음 시도에서는 DNS 확인에 실패했습니다
이틀 후 오류는 레지스트리 미러 호스트 이름에 대한 DNS 조회 실패로 바뀌었습니다. 따라서 커뮤니티 답변자는 이름 확인, 기본 HTTPS 연결, DNS 필터링, VPN/프록시 동작, 수동 이미지 가져오기를 점검하라고 제안했습니다.
이는 커뮤니티에서 제시한 진단 방법일 뿐, IceWhale이 확인한 근본 원인은 아닙니다.
현재 Paperless-ngx에서 Tika는 선택 사항입니다
현재 Paperless-ngx 문서에 따르면 Tika와 Gotenberg는 DOC/XLSX/ODT 같은 Office 문서와 이메일 구문 분석에 사용되는 선택적 서비스입니다. 이러한 형식이 필요하지 않다면 Tika를 활성화할 필요가 없습니다.
해당 형식이 필요하다면 오래된 앱 스토어 이미지 참조 대신 Tika와 Gotenberg가 포함된 유지 관리형 Compose 변형을 사용하세요.
현재 업스트림 Docker Compose를 기준으로 삼는 것이 가장 좋습니다
현재 Paperless-ngx 설정 가이드에서는 대부분의 사용자에게 Docker를 권장하며, 유지 관리되는 Compose 파일을 제공합니다. 새로 설치할 때는 PostgreSQL 사용을 권장하고, Tika가 활성화된 템플릿은 별도로 제공합니다.
ZimaOS 앱 스토어 패키지가 오래되었거나 사용할 수 없는 보조 이미지를 참조한다면 최신 Paperless-ngx Docker Compose 설치 방식을 사용하세요.
Tika 이미지만 변경하는 것으로는 충분하지 않을 수 있습니다
한 참여자는 Tika 이미지를 apache/tika:latest로 변경했습니다. 설치는 100%까지 진행되었지만, 시작 후에도 애플리케이션은 정상적으로 실행되지 않았습니다.
이 결과가 중요한 이유는 Paperless에서 서비스 엔드포인트, 기능 플래그, Gotenberg 통합 설정이 Compose 구성과 일치해야 하기 때문입니다. 컨테이너 이미지를 바꾸는 것만으로는 전체 스택이 완전히 이전되지 않을 수 있습니다.
Paperless 영구 데이터를 주 저장 공간에 보관하세요
Paperless의 저장 공간은 문서, 미리 보기 이미지, OCR 데이터, 검색 인덱스, 데이터베이스 때문에 계속 증가할 수 있습니다. 현재 ZimaOS에서는 저장 공간을 많이 사용하는 애플리케이션을 설치하기 전에 앱 데이터를 시스템 드라이브에서 옮길 것을 권장합니다.
현재 ZimaOS 앱 저장 경로 모델은 Paperless에 특히 중요합니다. 데이터 사용량이 Docker 이미지 크기를 훨씬 초과할 수 있기 때문입니다.
소비 폴더의 권한이 중요합니다
현재 Paperless-ngx 문서에서는 USERMAP_UID와 USERMAP_GID를 설정해 컨테이너가 호스트에 바인드 마운트된 폴더에 쓸 수 있도록 합니다. 스택은 설치되었지만 문서를 가져오지 못한다면 레지스트리 문제를 다시 확인하기보다 이 값과 호스트 폴더 권한을 점검하세요.
레지스트리 미러 호스트 이름을 Paperless 애플리케이션으로 간주하지 마세요
두 번째 원본 오류에는 기본 ghcr.io 엔드포인트가 아닌 미러 형식의 호스트 이름이 언급되었습니다. 이 구분이 중요한 이유는 애플리케이션 패키지는 완전히 정상이어도 구성된 이미지 미러, DNS 서버 또는 지역별 레지스트리 경로를 사용할 수 없을 수 있기 때문입니다.
업스트림 레지스트리에서 수동으로 이미지를 가져오는 데는 성공하지만 앱 스토어가 계속 고장 난 미러를 사용한다면, 문제는 Paperless 자체가 아니라 패키지 또는 레지스트리 라우팅 계층에 있습니다.
이미지 가져오기 실패와 컨테이너 시작 실패를 구분하세요
첫 번째 시도에서는 필요한 모든 이미지를 가져오는 작업이 완료되지 않았습니다. 이후 Apache Tika를 사용한 실험에서는 설치가 100%까지 진행되었지만 시작 후 실패했습니다. 이는 서로 다른 실패 단계이며, 각각 다른 증거가 필요합니다.
- 가져오기 단계: 레지스트리 인증, DNS, 미러 가용성, 이미지 태그
- 시작 단계: 환경 변수, 데이터베이스 연결, Tika/Gotenberg 엔드포인트, 볼륨, 권한, 상태 점검
앱 스토어 스택을 교체하기 전에 작동 중인 Paperless 인스턴스를 백업하세요
Paperless를 이미 사용 중이라면 보조 서비스를 수정하기 위해 문서와 데이터베이스를 먼저 보호하지 않고 Compose 템플릿을 바꾸지 마세요. 현재 업스트림 Paperless에는 백업과 마이그레이션을 위한 전용 내보내기 기능이 포함되어 있습니다.
새로 설치하는 경우 유지 관리되는 업스트림 Compose 파일로 시작하는 것이 더 간단합니다. 기존 설치라면 스택을 다시 작성하기 전에 현재 데이터베이스와 미디어 경로를 보존하세요.
Paperless-ngx 설치 FAQ
2025년의 실패가 확실히 DNS 문제였나요?
아니요. 스레드에는 인증 오류와 DNS 오류가 모두 나타났으며, 공식적인 최종 진단은 게시되지 않았습니다.
모든 Paperless-ngx 설치에 Tika가 필요한가요?
아니요. Tika는 선택 사항이며 주로 Office 문서와 이메일 구문 분석에 필요합니다.
apache/tika로 변경하면 원래 문제가 완전히 해결되었나요?
아니요. 한 사용자는 설치를 100%까지 진행했지만 애플리케이션은 여전히 실행되지 않았습니다.
