Instalação Paperless · 5 min read · Sep 25, 2025

Como Instalar Paperless com Nginx no Debian

Paperless é uma aplicação Python que ingere documentos digitalizados, os indexa e os apresenta em uma interface web amigável. Neste tutorial, vamos instalar o Paperless com um proxy reverso HTTPS Nginx no Debian 10.

  • Um sistema Debian 10 no qual você tenha acesso root.
  • Um nome de domínio registrado apontando para seu servidor.

Todos os comandos mostrados neste documento devem ser executados como root, a menos que indicado de outra forma.

Defina a variável de ambiente $VISUAL para um editor de texto de sua escolha. Por exemplo, para usar o nano:

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

O Paperless requer vários componentes de software para sua instalação e operação. Instale-os da seguinte forma:

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++

Se você vai trabalhar com documentos em idiomas diferentes do inglês, instale os arquivos de idioma Tesseract correspondentes. Por exemplo, para francês e espanhol:

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

Você pode listar todos os pacotes tesseract disponíveis usando:

apt list tesseract-ocr-*

Se você não tiver certeza de qual código de 3 letras corresponde ao idioma desejado, consulte esta Lista de Códigos ISO 639-2.

Embora seja possível executar o paperless como root, é fortemente recomendado usar um usuário com privilégios baixos e login desativado. Crie um usuário e grupo chamado paperless:

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

Clone o repositório do Paperless do Github para /opt/paperless

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

Dê ao usuário paperless a propriedade desse diretório:

chown -R paperless:paperless /opt/paperless

Copie o exemplo de configuração incluído como ponto de partida:

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

E abra-o em seu editor de texto:

$VISUAL /etc/paperless.conf

Escolha um diretório do qual o Paperless irá ingerir documentos digitalizados e defina o parâmetro PAPERLESS_CONSUMPTION_DIR de acordo:

PAPERLESS_CONSUMPTION_DIR="/opt/paperless/paper_in"

Encontre, descomente (removendo o caractere #) e altere os valores das seguintes linhas para algo seguro:

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

Se o seu scanner suportar o envio de documentos digitalizados por e-mail, você pode fazer com que o paperless os ingresse automaticamente a partir da caixa de entrada recebida. Para habilitar esse recurso, defina as opções PAPERLESSCONSUME_MAIL*. Por razões de segurança, recomenda-se criar uma conta de e-mail dedicada ao Paperless. Por exemplo:

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

Salve suas alterações e saia, em seguida, mude o proprietário deste arquivo para paperless e restrinja suas permissões:

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

Troque para o usuário paperless:

su - paperless

Crie o diretório de consumo:

mkdir /opt/paperless/paper_in

Crie um ambiente virtual Python. Isso fornecerá um ambiente estável e isolado onde podemos instalar os módulos e versões específicos do Python exigidos pelo Paperless.

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

Ative-o:

. venv/bin/activate

Instale os módulos Python exigidos pelo paperless:

pip3 install -r requirements.txt

Este comando pode demorar um pouco. Assim que terminar, execute os seguintes comandos para inicializar o banco de dados e criar os arquivos estáticos para o serviço web:

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

Crie credenciais de login para a conta de administrador da interface web executando o seguinte comando e respondendo aos prompts:

./manage.py createsuperuser

Antes de configurar um servidor web adequado e serviços systemd, tentaremos executar o paperless manualmente. Neste ponto, você ainda deve estar logado como paperless no ambiente virtual Python.

Inicie o servidor web e o consumidor de documentos em segundo plano:

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

Coloque qualquer documento digitalizado no diretório de consumo configurado na Etapa 3. Por exemplo:

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

Acesse http://IP_or_DOMAIN:8000/ e faça login com as credenciais escolhidas na Etapa 3. No menu “DOCUMENTOS”, clique em “Documentos” para visualizar a lista de documentos. Dentro de alguns minutos, o documento digitalizado deve ser processado e disponível.

Pare o paperless antes de prosseguir para a próxima etapa:

pkill -f manage.py

Vamos criar arquivos de unidade systemd para que possamos gerenciar adequadamente os serviços web e de consumidor. Saia de volta para seu shell root:

exit

Crie um arquivo de unidade para o serviço web:

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

E insira o seguinte:

[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

NOTA: Você pode querer modificar o número de processos de trabalho no comando ExecStart. O serviço mostrado aqui inicia o Gunicorn com 3 trabalhadores ( -w 3).

Em seguida, crie outro arquivo de unidade para o processo do consumidor de documentos:

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

E insira o seguinte:

[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

Inicie esses serviços:

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

Certifique-se de que ambos estão em execução:

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

Se você deseja que o paperless inicie automaticamente na inicialização do sistema, execute o comando:

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

Instale o Nginx e o certbot:

apt update
apt install -y nginx certbot

Certifique-se de que o Nginx esteja habilitado e em execução:

systemctl enable --now nginx.service

Obtenha um certificado Let’s Encrypt para seu domínio com o certbot:

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

Desative o arquivo de configuração padrão do Nginx e abra um novo:

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

Insira o seguinte, substitua your_domain pelo seu nome de domínio:

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;
    }
}

Habilite esta configuração criando um link para ela no diretório sites-enabled do Nginx e verifique se há erros:

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

Em seguida, carregue as alterações:

systemctl reload nginx.service

Sua instância Paperless agora deve estar acessível em https://your_domain.

Como o usuário do sistema paperless não precisa de acesso a um shell funcional após a configuração inicial, podemos alterá-lo para /usr/sbin/nologin:

usermod -s /usr/sbin/nologin paperless

Se o servidor web Gunicorn falhar ao iniciar com a mensagem de erro [ERROR] Connection in use, verifique se há processos já vinculados à porta 8000/tcp:

ss -lntp

Mate/desative o processo ofensivo, se necessário, ou modifique /etc/systemd/system/paperless-webserver.service e /etc/nginx/sites-enabled/paperless para usar outra porta de rede para o Gunicorn.

Share: X/Twitter LinkedIn
#Instalação Paperless

Receba novas postagens na sua caixa de entrada

Sem spam. Cancele a assinatura a qualquer momento.