Paperless-ngx: gestão de documentos com OCR no seu próprio servidor

Notas fiscais, contratos, boletos, laudos e comprovantes chegam todo dia, em papel e por e-mail. Sem um lugar central, eles se espalham entre pastas de rede, caixas de entrada e gavetas, e achar um documento de dois anos atrás vira uma caça ao tesouro.

O Paperless-ngx resolve isso. Ele é um sistema de gestão de documentos de código aberto que digitaliza, faz OCR, classifica e indexa tudo num arquivo pesquisável, rodando no seu próprio servidor. Neste artigo mostramos o que ele faz e como colocá-lo no ar com Docker num container LXC do Proxmox.

O que é o Paperless-ngx

O Paperless-ngx é o sucessor oficial dos projetos Paperless e Paperless-ng, mantido por uma comunidade no GitHub. A versão atual é a 3.3. Os documentos ficam no seu servidor e não são enviados a ninguém, a menos que você ative de propósito algum recurso externo.

Os principais recursos:

• OCR em mais de 100 idiomas, com o Tesseract, incluindo português. Até documento escaneado como imagem vira texto pesquisável e selecionável.
• Arquivo em PDF/A, o formato feito para guarda de longo prazo, sempre ao lado do original, que nunca é alterado.
• Classificação automática: um modelo de aprendizado de máquina treinado com os seus próprios documentos sugere tags, correspondentes e tipos.
• Busca de texto completo, com autocompletar, destaque dos trechos encontrados e busca por documentos parecidos.
• Importação de e-mail: várias contas e regras, com ações como marcar como lido ou apagar depois de importar.
• Workflows: regras que agem quando um documento chega ou é alterado, atribuindo tags, permissões, enviando e-mail ou chamando um webhook.
• Usuários e permissões globais e por documento, com autenticação em dois fatores.
• Arquivos do Office (Word, Excel, PowerPoint e equivalentes do LibreOffice) e e-mails .eml, com o Apache Tika e o Gotenberg.
• Recursos de IA opcionais: sugestões e chat com os documentos, usando um modelo local via Ollama ou uma API compatível com a OpenAI. Vêm desligados por padrão.

Painel inicial do Paperless-ngx. Imagem: documentação oficial do projeto.

Como ele organiza os documentos

O Paperless não usa pastas. Cada documento recebe metadados, e são eles que permitem filtrar e encontrar:

As tags funcionam como pastas mais poderosas: o mesmo documento pode estar em "Financeiro" e em "Cliente X" ao mesmo tempo, o que pasta nenhuma permite.

Como os documentos entram

Ao receber um arquivo, o Paperless faz três coisas: roda o OCR, se o documento ainda não tiver texto; gera a versão PDF/A de arquivo; e aplica as regras de classificação automática. Há quatro formas de enviar:

1. Pela interface web: o botão de envio no painel ou arrastar o arquivo para qualquer lugar da tela.
2. Pasta de consumo: tudo o que cair na pasta consume é importado e removido dela. Compartilhe essa pasta por Samba ou FTP e configure o scanner da empresa para salvar direto nela.
3. E-mail: o Paperless lê uma caixa de e-mail e importa os anexos conforme as regras que você criar.
4. API REST: para integrar com outros sistemas e scripts.

Instalando com Docker num LXC do Proxmox

Usamos um container LXC com Debian 13, 2 vCPUs, 4 GB de RAM e disco de 28 GB. Com a pilha completa, incluindo o suporte a Office, a instalação ocupou cerca de 5 GB. Um disco de 8 GB é pequeno demais para isso, então reserve pelo menos 20 GB.

1. Instalar o Docker no LXC

apt update
apt install -y docker.io docker-compose curl
docker run --rm hello-world

2. Criar a pasta e o compose

O projeto oferece arquivos prontos para SQLite, PostgreSQL e MariaDB, com ou sem Tika. Esta é a variante com PostgreSQL, Tika e Gotenberg, que suporta arquivos do Office:

mkdir -p /opt/paperless/{consume,export} && cd /opt/paperless

# /opt/paperless/docker-compose.yml
services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data
  db:
    image: docker.io/library/postgres:18
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: troque-esta-senha
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on: [db, broker, gotenberg, tika]
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
      PAPERLESS_DBPASS: troque-esta-senha
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.37
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=^file:///tmp/.*"
  tika:
    image: docker.io/apache/tika:3.3.1.0
    restart: unless-stopped
volumes:
  data:
  media:
  pgdata:
  redisdata:

3. Configurar o ambiente

A partir da versão 3, a PAPERLESS_SECRET_KEY é obrigatória. Gere uma chave aleatória e configure o OCR em português:

cat > /opt/paperless/docker-compose.env <<EOF
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
PAPERLESS_URL=http://IP-DO-SERVIDOR:8000
PAPERLESS_TIME_ZONE=America/Sao_Paulo
PAPERLESS_OCR_LANGUAGE=por
PAPERLESS_OCR_LANGUAGES=por
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=troque-esta-senha
EOF

O português não vem instalado na imagem, que traz inglês, alemão, italiano, espanhol e francês. Por isso são duas variáveis: PAPERLESS_OCR_LANGUAGES instala o pacote do idioma ao iniciar o container, e PAPERLESS_OCR_LANGUAGE define o idioma usado no OCR.

4. Subir

docker compose pull
docker compose up -d
docker compose ps

Na primeira vez, o Paperless cria o banco e o usuário administrador. Em cerca de um minuto, a interface responde em http://IP-DO-SERVIDOR:8000.

Primeiros passos depois de instalar

1. Cadastre os correspondentes e os tipos de documento que você mais usa. A classificação automática aprende com eles.
2. Crie uma tag de entrada (por exemplo, "Caixa de entrada") e marque-a como tag de inbox. Todo documento novo chega com ela, e você revisa e tira a tag.
3. Envie alguns documentos e corrija as sugestões. Quanto mais documentos classificados, melhores as sugestões.
4. Configure a pasta de consumo no scanner ou uma regra de e-mail para os documentos que chegam sempre pelo mesmo caminho.
5. Crie workflows para o que se repete, como "todo documento do correspondente Copel recebe a tag Energia".

Lista de documentos com filtros, tags e correspondentes. Imagem: documentação oficial do projeto.

Backup

O Paperless tem um exportador próprio, que gera uma cópia completa (documentos, metadados e configurações) restaurável em outra instalação:

cd /opt/paperless
docker compose exec -T webserver document_exporter ../export

Os arquivos vão para /opt/paperless/export. Agende o comando no cron e inclua essa pasta na rotina de backup do servidor. Num Proxmox, um backup do LXC pelo Proxmox Backup Server complementa a proteção.

O que o Paperless não faz

O Paperless é um arquivo de documentos, não um editor. Arquivos do Word ou do Excel são indexados e mostrados como PDF, mas não podem ser editados dentro dele: para alterar, baixe o original, edite e envie a nova versão. Se a equipe precisa editar documentos no navegador, combine-o com um Nextcloud com Collabora ou OnlyOffice e mande para o Paperless só a versão final.

Conclusão

Com algumas horas de configuração, o Paperless-ngx transforma papel e anexos espalhados num arquivo único, pesquisável e organizado automaticamente, guardado no seu próprio servidor. Ele roda bem num LXC pequeno do Proxmox e cresce com o uso: quanto mais documentos você classifica, melhor ele fica em classificar sozinho.

Precisa de ajuda para implantar o Paperless-ngx ou integrá-lo aos seus scanners, e-mail e backup? Fale com a TRIAT.