설치 가이드 · 4 min read · Sep 25, 2025

Debian에서 Nginx로 Paperless 설치하는 방법

Paperless는 스캔한 문서를 수집하고, 인덱싱하며, 사용자 친화적인 웹 인터페이스에서 제공하는 Python 애플리케이션입니다. 이 튜토리얼에서는 Debian 10에서 Nginx HTTPS 리버스 프록시와 함께 Paperless를 설치할 것입니다.

  • 루트 접근 권한이 있는 Debian 10 시스템.
  • 서버를 가리키는 등록된 도메인 이름.

이 문서에 표시된 모든 명령은 별도로 표시되지 않는 한 루트로 실행해야 합니다.

$VISUAL 환경 변수를 선택한 텍스트 편집기로 설정합니다. 예를 들어, nano를 사용하려면:

echo "export VISUAL=nano" >> ~/.bashrc
. ~/.bashrc

Paperless는 설치 및 운영을 위해 여러 소프트웨어 구성 요소가 필요합니다. 다음과 같이 설치합니다:

apt update
apt install -y gnupg2 python3 python3-dev python3-pip python3-virtualenv tesseract-ocr tesseract-ocr-eng unpaper imagemagick libpoppler-cpp-dev optipng git gcc g++

영어 외의 언어로 문서를 작업할 예정이라면, 해당 Tesseract 언어 파일을 설치합니다. 예를 들어, 프랑스어와 스페인어의 경우:

apt install -y tesseract-ocr-fra tesseract-ocr-spa

사용 가능한 모든 tesseract 패키지를 나열하려면:

apt list tesseract-ocr-*

원하는 언어에 해당하는 3자리 코드가 무엇인지 확실하지 않은 경우, 이 ISO 639-2 코드 목록을 참조하십시오.

Paperless를 루트로 실행하는 것이 가능하지만, 낮은 권한을 가진 사용자와 로그인 비활성화를 사용하는 것이 강력히 권장됩니다. paperless라는 이름의 사용자 및 그룹을 생성합니다:

useradd -d /opt/paperless -M -r -s /bin/bash -U -p x paperless

Paperless Github 리포지토리를 /opt/paperless에 클론합니다:

git clone https://github.com/the-paperless-project/paperless.git /opt/paperless

paperless 사용자에게 해당 디렉토리의 소유권을 부여합니다:

chown -R paperless:paperless /opt/paperless

포함된 구성 샘플을 시작점으로 복사합니다:

cp /opt/paperless/paperless.conf.example /etc/paperless.conf

텍스트 편집기에서 엽니다:

$VISUAL /etc/paperless.conf

Paperless가 스캔한 문서를 수집할 디렉토리를 선택하고 PAPERLESS_CONSUMPTION_DIR 매개변수를 accordingly 설정합니다:

PAPERLESS_CONSUMPTION_DIR="/opt/paperless/paper_in"

다음 줄의 값을 안전한 것으로 변경하기 위해 주석을 제거합니다( # 문자를 제거하여):

#PAPERLESS_PASSPHRASE="secret"
#PAPERLESS_SECRET_KEY="change-me"

스캐너가 스캔한 문서를 이메일로 전송하는 것을 지원하는 경우, paperless가 수신함에서 자동으로 수집하도록 설정할 수 있습니다. 이 기능을 활성화하려면 PAPERLESSCONSUME_MAIL* 옵션을 설정합니다. 보안상의 이유로 Paperless 전용 메일 계정을 만드는 것이 좋습니다. 예를 들어:

PAPERLESS_CONSUME_MAIL_HOST="imap.example.com"
PAPERLESS_CONSUME_MAIL_PORT="993"
PAPERLESS_CONSUME_MAIL_USER="[email protected]"
PAPERLESS_CONSUME_MAIL_PASS="imap_password"

변경 사항을 저장하고 종료한 후, 이 파일의 소유자를 paperless로 변경하고 권한을 강화합니다:

chown paperless:paperless /etc/paperless.conf
chmod 0400 /etc/paperless.conf

paperless 사용자로 전환합니다:

su - paperless

소비 디렉토리를 생성합니다:

mkdir /opt/paperless/paper_in

Python 가상 환경을 생성합니다. 이는 Paperless에 필요한 특정 Python 모듈 및 버전을 설치할 수 있는 안정적이고 격리된 환경을 제공합니다.

python3 -m virtualenv --python=/usr/bin/python3 venv

활성화합니다:

. venv/bin/activate

paperless에 필요한 Python 모듈을 설치합니다:

pip3 install -r requirements.txt

이 명령은 시간이 걸릴 수 있습니다. 완료되면 다음 명령을 실행하여 데이터베이스를 초기화하고 웹 서비스의 정적 파일을 생성합니다:

cd src/
./manage.py migrate
./manage.py collectstatic

웹 인터페이스 관리자 계정의 로그인 자격 증명을 생성하려면 다음 명령을 실행하고 프롬프트에 응답합니다:

./manage.py createsuperuser

적절한 웹 서버 및 systemd 서비스를 설정하기 전에, paperless를 수동으로 실행해 보겠습니다. 이 시점에서 여전히 가상 Python 환경에서 paperless로 로그인되어 있어야 합니다.

웹 서버와 문서 소비자를 백그라운드에서 시작합니다:

./manage.py runserver 0.0.0.0:8000 &
./manage.py document_consumer &

3단계에서 구성한 소비 디렉토리에 스캔한 문서를 배치합니다. 예를 들어:

wget https://i.imgur.com/DPr5wWG.jpg -O /opt/paperless/paper_in/test1.jpg

http://IP_or_DOMAIN:8000/로 이동하여 3단계에서 선택한 자격 증명으로 로그인합니다. “DOCUMENTS” 메뉴에서 “Documents”를 클릭하여 문서 목록을 봅니다. 몇 분 이내에 스캔한 문서가 처리되어 사용할 수 있어야 합니다.

다음 단계로 진행하기 전에 paperless를 중지합니다:

pkill -f manage.py

웹 및 소비 서비스 관리를 위해 systemd 유닛 파일을 생성합니다. 루트 셸로 다시 종료합니다:

exit

웹 서비스에 대한 유닛 파일을 생성합니다:

$VISUAL /etc/systemd/system/paperless-webserver.service

다음 내용을 입력합니다:

[Unit]
Description=Paperless Gunicorn Web Server
Requires=network.target
[Service]
User=paperless
Group=paperless
ExecStart=/opt/paperless/venv/bin/gunicorn --pythonpath=/opt/paperless/src paperless.wsgi -w 3 -b 127.0.0.1:8000
Restart=on-failure
[Install]
WantedBy=multi-user.target

참고: ExecStart 명령에서 작업자 프로세스 수를 수정할 수 있습니다. 여기에서 표시된 서비스는 3개의 작업자(-w 3)로 Gunicorn을 시작합니다.

다음으로 문서 소비자 프로세스에 대한 또 다른 유닛 파일을 생성합니다:

$VISUAL /etc/systemd/system/paperless-consumer.service

다음 내용을 입력합니다:

[Unit]
Description=Paperless Document Consumer
Requires=network.target
[Service]
User=paperless
Group=paperless
ExecStart=/opt/paperless/venv/bin/python3 /opt/paperless/src/manage.py document_consumer
Restart=on-failure
[Install]
WantedBy=multi-user.target

이 서비스를 시작합니다:

systemctl daemon-reload
systemctl start paperless-webserver.service paperless-consumer.service

두 서비스가 모두 실행 중인지 확인합니다:

systemctl status paperless-webserver.service paperless-consumer.service

paperless가 시스템 시작 시 자동으로 시작되도록 하려면 다음 명령을 실행합니다:

systemctl enable paperless-webserver.service paperless-consumer.service

Nginx 및 certbot을 설치합니다:

apt update
apt install -y nginx certbot

Nginx가 활성화되고 실행 중인지 확인합니다:

systemctl enable --now nginx.service

certbot을 사용하여 도메인에 대한 Let’s Encrypt 인증서를 얻습니다:

certbot certonly --webroot --webroot-path /var/www/html -d your_domain

기본 Nginx 구성 파일을 비활성화하고 새 파일을 엽니다:

rm /etc/nginx/sites-enabled/default
$VISUAL /etc/nginx/sites-available/paperless

다음 내용을 입력하고 your_domain을 도메인 이름으로 바꿉니다:

server {
    listen 80;
    server_name your_domain;
    return 301 https://$server_name$request_uri;
    access_log /var/log/nginx/paperless_access.log;
    error_log /var/log/nginx/paperless_error.log;
}
server {
    listen 443 ssl;
    server_name your_domain;
    index index.html index.htm index.php;
    access_log /var/log/nginx/paperless_access.log;
    error_log /var/log/nginx/paperless_error.log;
    ssl on;
    ssl_certificate /etc/letsencrypt/live/your_domain/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your_domain/privkey.pem;
    location /static {
        autoindex on;
        alias /opt/paperless/static;
    }
    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:8000;
    }
}

이 구성을 sites-enabled Nginx 디렉토리에 링크하여 활성화하고 오류가 있는지 확인합니다:

ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled
nginx -t

변경 사항을 로드합니다:

systemctl reload nginx.service

이제 Paperless 인스턴스에 https://your_domain에서 접근할 수 있어야 합니다.

paperless 시스템 사용자는 초기 설정 후 작동하는 셸에 접근할 필요가 없으므로 /usr/sbin/nologin으로 변경할 수 있습니다:

usermod -s /usr/sbin/nologin paperless

Gunicorn 웹 서버가 [ERROR] Connection in use 오류 메시지와 함께 시작되지 않는 경우, 포트 8000/tcp에 이미 바인딩된 프로세스가 있는지 확인합니다:

ss -lntp

필요한 경우 문제의 프로세스를 종료/비활성화하거나 /etc/systemd/system/paperless-webserver.service 및 /etc/nginx/sites-enabled/paperless를 수정하여 Gunicorn에 다른 네트워크 포트를 사용하도록 설정합니다.

Share: X/Twitter LinkedIn
#설치 가이드

새 게시물을 받은 편지함에서 받기

스팸은 없습니다. 언제든지 구독 해지 가능합니다.