Develop

홈서버 구축기 — MariaDB + Redis + Paperless-ngx 설치 및 외부 접속 설정

괴남 2026. 5. 9. 22:57
반응형

홈서버 구축기 — MariaDB + Redis + Paperless-ngx 설치 및 외부 접속 설정

Mac mini 2012 Late (Ubuntu 24.04, Docker) 기반 홈서버에 MariaDB, Redis, Paperless-ngx를 설치하고 Cloudflare Tunnel로 외부 접속까지 설정한 과정을 정리합니다.

전체 구성 개요

~/stacks/
├── shared/           ← MariaDB + Redis (공용)
│   ├── docker-compose.yml
│   └── mariadb-data/
└── paperless/        ← Paperless-ngx
    ├── docker-compose.yml
    ├── docker-compose.env
    ├── Dockerfile
    └── data/
        ├── consume/
        ├── media/
        ├── export/
        └── data/

MariaDB와 Redis는 shared 스택으로 분리해 Nextcloud, n8n 등 다른 서비스에서도 재사용할 수 있도록 구성했습니다.

1. MariaDB + Redis 설치

폴더 생성

mkdir -p ~/stacks/shared
cd ~/stacks/shared

docker-compose.yml 작성

vi ~/stacks/shared/docker-compose.yml
services:
  db:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: your_root_password
      MARIADB_DATABASE: paperless
      MARIADB_USER: paperless
      MARIADB_PASSWORD: your_password
    volumes:
      - ./mariadb-data:/var/lib/mysql
    command: >
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
      --transaction-isolation=READ-COMMITTED
      --binlog-format=ROW
    ports:
      - "3306:3306"

  redis:
    image: redis:7
    restart: unless-stopped
    ports:
      - "6379:6379"

networks:
  default:
    name: shared-network
    driver: bridge

MariaDB 설정 포인트:

  • utf8mb4 + utf8mb4_unicode_ci: 한국어 포함 다국어 지원
  • READ-COMMITTED + ROW: Paperless-ngx 필수 요구사항
  • shared-network: 다른 스택에서 이 DB/Redis를 참조할 수 있도록 네트워크 이름 고정

실행

docker compose up -d

정상 확인

# MariaDB 접속 테스트
docker exec -it shared-db-1 mariadb -u paperless -pyour_password paperless -e "SELECT 1;"

# Redis 접속 테스트
docker exec -it shared-redis-1 redis-cli ping
# PONG 나오면 정상

2. Paperless-ngx 설치

폴더 및 데이터 디렉토리 생성

mkdir -p ~/stacks/paperless
mkdir -p ~/stacks/paperless/data/{data,media,consume,export}
cd ~/stacks/paperless

Dockerfile 작성 (한국어 OCR 포함)

Paperless-ngx 공식 이미지에는 한국어 Tesseract 언어팩이 없어서 직접 빌드합니다.

vi ~/stacks/paperless/Dockerfile
FROM paperlessngx/paperless-ngx:latest
RUN apt-get update && apt-get install -y tesseract-ocr-kor && rm -rf /var/lib/apt/lists/*

docker-compose.yml 작성

vi ~/stacks/paperless/docker-compose.yml
services:
  webserver:
    build: .
    restart: unless-stopped
    depends_on:
      - gotenberg
      - tika
    ports:
      - "8010:8000"
    volumes:
      - ./data/data:/usr/src/paperless/data
      - ./data/media:/usr/src/paperless/media
      - ./data/consume:/usr/src/paperless/consume
      - ./data/export:/usr/src/paperless/export
    env_file: docker-compose.env

  gotenberg:
    image: gotenberg/gotenberg:8
    restart: unless-stopped

  tika:
    image: apache/tika:latest
    restart: unless-stopped

networks:
  default:
    name: shared-network
    external: true

포인트:

  • build: .: 직접 빌드한 이미지 사용 (한국어 OCR 포함)
  • gotenberg: Office 문서(docx, xlsx 등) → PDF 변환
  • tika: 텍스트 추출 보조
  • shared-network: external: true: shared 스택의 MariaDB/Redis 참조

환경변수 파일 작성

vi ~/stacks/paperless/docker-compose.env
# 데이터베이스
PAPERLESS_DBENGINE=mariadb
PAPERLESS_DBHOST=shared-db-1
PAPERLESS_DBPORT=3306
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=your_password

# Redis
PAPERLESS_REDIS=redis://shared-redis-1:6379/0

# 서버 설정
PAPERLESS_URL=https://paperless.yourdomain.com
PAPERLESS_CSRF_TRUSTED_ORIGINS=https://paperless.yourdomain.com
PAPERLESS_SECRET_KEY=여기에_openssl_rand_-hex_32_결과값
PAPERLESS_TIME_ZONE=Asia/Seoul
PAPERLESS_OCR_LANGUAGE=kor+eng

# 리소스 제한 (구형 하드웨어 배려)
PAPERLESS_TASK_WORKERS=1
PAPERLESS_THREADS_PER_WORKER=1

# Tika / Gotenberg
PAPERLESS_TIKA_ENABLED=1
PAPERLESS_TIKA_ENDPOINT=http://tika:9998
PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000

SECRET_KEY 생성:

openssl rand -hex 32

빌드 및 실행

docker compose up -d --build

관리자 계정 생성

docker exec -it paperless-webserver-1 python3 manage.py createsuperuser

3. Cloudflare Tunnel 연동

이미 cloudflared가 설치되어 있고 터널이 운영 중인 상태에서 Paperless를 추가합니다.

config.yml에 Paperless 추가

sudo vi /etc/cloudflared/config.yml
ingress:
  - hostname: ssh.yourdomain.com
    service: ssh://localhost:22
  - hostname: portainer.yourdomain.com
    service: https://localhost:9443
    originRequest:
      noTLSVerify: true
  - hostname: paperless.yourdomain.com
    service: http://localhost:8010
  - service: http_status:404

DNS 레코드 등록

cloudflared tunnel route dns your-server-name paperless.yourdomain.com

cloudflared 재시작

sudo systemctl restart cloudflared

이후 https://paperless.yourdomain.com 으로 외부 접속 가능합니다.

4. DataGrip으로 MariaDB 외부 접속 (SSH 터널링)

~/.ssh/config 설정 (맥북 기준)

Host your-server-name
  HostName ssh.yourdomain.com
  User your_username
  ProxyCommand cloudflared access ssh --hostname %h

Host mac-mini-db
  HostName ssh.yourdomain.com
  User your_username
  ProxyCommand cloudflared access ssh --hostname %h
  LocalForward 3307 127.0.0.1:3306

사용 방법

터미널에서 터널 열기:

ssh mac-mini-db -N

DataGrip 접속 설정:

Host     : 127.0.0.1
Port     : 3307
User     : root
Password : your_root_password

-N 옵션은 쉘 없이 포트포워딩 터널만 유지하는 옵션입니다.

트러블슈팅

ghcr.io 이미지 pull 실패

한국에서 GitHub Container Registry 접근이 막히는 경우가 있습니다.

# 변경 전
image: ghcr.io/paperless-ngx/paperless-ngx:latest
image: ghcr.io/paperless-ngx/tika:latest

# 변경 후
image: paperlessngx/paperless-ngx:latest  (Docker Hub)
image: apache/tika:latest                  (Docker Hub)

Portainer와 포트 충돌 (8000)

Portainer가 8000 포트를 사용 중이라 Paperless를 8010으로 변경했습니다.

ports:
  - "8010:8000"

CSRF 검증 실패

외부 도메인으로 접속 시 CSRF 오류가 발생하면 환경변수에 추가:

PAPERLESS_URL=https://paperless.yourdomain.com
PAPERLESS_CSRF_TRUSTED_ORIGINS=https://paperless.yourdomain.com

한국어 OCR 언어팩 컨테이너 재시작 시 초기화

컨테이너 내부에 직접 설치한 패키지는 재시작 시 사라집니다. Dockerfile로 이미지를 직접 빌드하면 영구적으로 유지됩니다.

FROM paperlessngx/paperless-ngx:latest
RUN apt-get update && apt-get install -y tesseract-ocr-kor && rm -rf /var/lib/apt/lists/*

서비스별 Redis DB 번호 분리

향후 다른 서비스 추가 시 Redis DB 번호로 격리:

Paperless-ngx → redis://shared-redis-1:6379/0
n8n           → redis://shared-redis-1:6379/1
Nextcloud     → redis://shared-redis-1:6379/2

최종 접속 정보

서비스 내부 접속 외부 접속
Paperless-ngx http://192.168.x.x:8010 https://paperless.yourdomain.com
MariaDB 192.168.x.x:3306 ssh mac-mini-db -N → 127.0.0.1:3307
반응형
저작자표시 비영리 (새창열림)