Base de Conhecimento

Paperless-ngx na VPS: documentos organizados no servidor

  • paperless-ngx, documentos, docker compose, ocr, autohospedagem, vps
  • Usuários acharam útil: 0

Aprenda a instalar o Paperless-ngx v3.4.2 na sua VPS com Docker Compose: aviso de segurança do projeto, variáveis, OCR em português, backup e atualização.

Por Redação Eleven Host · @robson.direitodigital · 4 de novembro de 2026 · 10 min de leitura

Arte da Eleven Host: janela de terminal com o título: Paperless-ngx na VPS: documentos organizados no servidor

Capa da Redação Eleven Host para o guia: Paperless-ngx na VPS: documentos organizados no servidor Arte: Eleven Host

Paperless-ngx na VPS: o Paperless-ngx é um sistema de gerenciamento de documentos que transforma documentos físicos em um arquivo online pesquisável. Veja a instalação com Docker Compose, o OCR em português, o backup e a atualização.

A v3.4.2 é a release mais recente no GitHub do projeto na data deste texto, e os arquivos do Compose citados aqui são dessa versão. Se você ainda está conhecendo o assunto, o guia O que é servidor VPS explica o básico do servidor onde o Paperless-ngx vai ficar.

Leia o aviso do projeto antes de instalar

O README do Paperless-ngx traz uma nota importante. Ele lembra que scanners são usados com documentos sensíveis, como dados pessoais, declarações de impostos e faturas, e diz que o Paperless-ngx não deve ser executado num host não confiável, porque as informações ficam armazenadas em texto puro, sem criptografia. O projeto também afirma que não dá garantias de segurança e que o uso é por conta e risco de quem instala. Segundo o README, a forma mais segura de rodar o Paperless-ngx é num servidor local, na sua casa, com backups feitos.

Segundo o projeto, o Paperless-ngx guarda os documentos sem criptografia e não deve rodar num host não confiável.

Recomendamos pesar isso antes de colocar documentos pessoais ou da empresa num servidor remoto. Numa VPS, o servidor e as pessoas com acesso a ele precisam ser de confiança, e os arquivos ficam sem criptografia no disco.

O que é o Paperless-ngx e qual é a licença

O projeto se descreve como um sistema de gerenciamento de documentos que transforma seus documentos físicos em um arquivo online pesquisável, para você guardar menos papel. Entre os recursos, está organizar e indexar os documentos digitalizados com etiquetas, correspondentes, tipos e outros campos.

A licença é a GNU General Public License, versão 3, de 29 de junho de 2007.

Requisitos para instalar

O arquivo do Compose oficial informa que o Paperless suporta hardware amd64, arm e arm64. A documentação diz que ele roda num Raspberry Pi, e que algumas tarefas podem ficar lentas em hardware mais fraco. Com Docker, ajustar a variável PAPERLESS_WEBSERVER_WORKERS para 1 economiza memória.

Você precisa do Docker e do plugin docker compose instalados no servidor. O script de instalação oficial também usa o wget e se recusa a rodar como root, então use um usuário comum com permissão para o Docker.

Que servidor sustenta os seus sistemas hoje? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver as VPS

Instalação pelo script oficial

A documentação oferece um script que faz as perguntas e monta tudo. O comando abaixo é o da documentação:

bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

A própria documentação avisa que, se mandar um script da internet direto para o shell deixa você desconfortável, o melhor é baixar e ler o script antes de rodar.

O script pergunta, com valores padrão:

  • a URL de acesso (vira a variável PAPERLESS_URL), a porta (8000) e o fuso horário;
  • o banco de dados: postgres, sqlite ou mariadb (o padrão é postgres);
  • se quer usar o Apache Tika (não, por padrão);
  • o idioma do OCR (eng, por padrão);
  • os valores USERMAP_UID e USERMAP_GID (os do seu usuário);
  • as pastas de destino (./paperless-ngx, com a pasta de entrada em consume dentro dela);
  • o nome, a senha e o e-mail do superusuário.

Depois das respostas, o script baixa o arquivo do Compose do banco escolhido, gera a PAPERLESS_SECRET_KEY com 64 caracteres aleatórios, baixa as imagens com docker compose pull, cria o superusuário e sobe tudo com docker compose up --detach.

Instalação manual com Docker Compose

Se prefere montar à mão, os arquivos estão na pasta docker/compose do repositório: docker-compose.postgres.yml, docker-compose.sqlite.yml, docker-compose.mariadb.yml (e as versões com Tika), mais o docker-compose.env e o .env. A documentação recomenda o PostgreSQL para instalações novas.

O cabeçalho do arquivo do Compose resume os passos:

  • copie o arquivo como docker-compose.yml e os arquivos docker-compose.env e .env para uma mesma pasta;
  • rode o docker compose pull;
  • rode o docker compose up -d.

docker compose pull

docker compose up -d

O Paperless escuta na porta 8000, e as pastas de importação (consume) e de exportação (export) são criadas ao lado do arquivo do Compose. A documentação indica o endereço http://127.0.0.1:8000 para acessar a instância. Para mudar a porta externa, mapeie outra porta no Compose, como 8010:8000.

O arquivo do Compose oficial publica a porta 8000 e usa a senha paperless para o banco PostgreSQL. Recomendamos trocar essa senha no POSTGRES_PASSWORD e, numa VPS, publicar a porta só no próprio servidor, com "127.0.0.1:8000:8000", deixando um proxy na frente (veja a seção sobre HTTPS mais adiante).

Variáveis do docker-compose.env

O arquivo docker-compose.env traz as variáveis principais. Estas são as que mais importam no começo:

PAPERLESS_URL=https://paperless.example.com

PAPERLESS_SECRET_KEY=change-me

PAPERLESS_TIME_ZONE=America/Sao_Paulo

  • PAPERLESS_SECRET_KEY: é obrigatória, e o Paperless se recusa a iniciar sem ela. O arquivo vem com change-me e sugere gerar o valor com python3 -c "import secrets; print(secrets.token_urlsafe(64))". A documentação diz que a chave deve ser uma sequência aleatória de caracteres e que, sem isso, terceiros podem forjar credenciais de autenticação.
  • PAPERLESS_URL: o arquivo diz que ela é necessária se você expõe o Paperless-ngx num domínio público, e a documentação manda defini-la atrás de um proxy reverso. Não coloque barra no final. No arquivo, ela vem comentada, com o exemplo https://paperless.example.com.
  • PAPERLESS_TIME_ZONE: o padrão é UTC. Para o horário do Brasil, o valor America/Sao_Paulo é um exemplo.

O arquivo também explica o USERMAP_UID e o USERMAP_GID: use o UID e o GID do seu usuário no servidor para ter permissão de escrita na pasta de entrada de documentos.

Criar o superusuário

Na instalação manual, ao abrir a interface web pela primeira vez, o Paperless pede que você crie uma conta de superusuário. No script, ela é criada com o nome e a senha que você informa. Segundo a documentação, um superusuário acessa as partes da aplicação e os objetos do sistema inteiro.

Outra opção é definir PAPERLESS_ADMIN_USER e PAPERLESS_ADMIN_PASSWORD. Com elas, o Paperless cria um superusuário ao iniciar, e isso não muda a senha de um superusuário que já existe.

Os comandos de gestão no Docker seguem o formato docker compose exec webserver <comando> <argumentos>. Seguindo esse padrão, este é um exemplo para criar outro superusuário:

docker compose exec webserver createsuperuser

OCR em português

O OCR lê o texto dos documentos digitalizados. Segundo a documentação, o Paperless faz o OCR do documento quando ele não tem texto e cria um PDF/A arquivável. O idioma é definido pela variável PAPERLESS_OCR_LANGUAGE, com o código de três letras do idioma; o padrão é eng. Para vários idiomas, junte os códigos com o sinal de mais, como deu+eng. Quanto mais idiomas, mais processamento.

O detalhe importante: a imagem vem com inglês, alemão, italiano, espanhol e francês. O português não vem instalado. Para usá-lo, instale o idioma pela variável PAPERLESS_OCR_LANGUAGES, que é uma lista separada por espaços e, por padrão, não instala nenhum idioma extra, e depois selecione o idioma em PAPERLESS_OCR_LANGUAGE. No docker-compose.env, fica assim:

PAPERLESS_OCR_LANGUAGES=por

PAPERLESS_OCR_LANGUAGE=por

Para documentos que misturam português e inglês, o exemplo por+eng segue o formato da documentação:

PAPERLESS_OCR_LANGUAGE=por+eng

Como enviar documentos

Segundo a documentação, o método principal para colocar documentos no banco é copiá-los para a pasta de consumo (consume). Dentro do Docker, não altere o PAPERLESS_CONSUMPTION_DIR, porque ele só muda o caminho dentro do contêiner. Também dá para enviar pelo botão de upload ou arrastando arquivos na interface web, por aplicativos de celular de terceiros, por regras de e-mail e pela API REST.

Para outros tipos de conteúdo, veja o Immich na VPS: suas fotos e vídeos no seu servidor, para fotos, e o BookStack na VPS: wiki da empresa no seu servidor, para a documentação da empresa.

Proxy reverso e HTTPS

O arquivo docker-compose.env diz que a PAPERLESS_URL é necessária ao expor o Paperless-ngx num domínio público, e pede que se considerem medidas de segurança, como um proxy reverso. A documentação aponta para a wiki do projeto, mantida pelos usuários, com orientações sobre nginx e sobre ferramentas como o Fail2ban.

A configuração de HTTPS é recomendação nossa, e não passo da documentação. Recomendamos colocar um proxy com HTTPS na frente do Paperless-ngx e manter a porta 8000 fechada para a internet. O guia Caddy na VPS: servidor web com HTTPS automático mostra uma forma de fazer isso. Depois, ajuste a PAPERLESS_URL para o endereço com HTTPS.

Backup com o document_exporter

Segundo a documentação, os dados ficam em volumes do Docker: paperless_media (os documentos), paperless_data (os dados e o SQLite), e paperless_pgdata (PostgreSQL) ou paperless_dbdata (MariaDB). Em geral, ficam em /var/lib/docker/volumes, que exige permissão de root.

O jeito oficial de exportar é o document_exporter. O -T evita o erro de terminal quando o comando roda em tarefas agendadas, como o cron:

docker compose exec -T webserver document_exporter ../export

A exportação vai para a pasta export, ao lado do arquivo do Compose. Dois avisos da documentação: o exportador não inclui tokens de API, que precisam ser gerados de novo depois da importação, e não é possível importar uma exportação feita numa versão do Paperless em uma versão diferente. Para restaurar, o document_importer serve para uma instalação completamente vazia. Recomendamos copiar a pasta export para fora da VPS.

Como atualizar

Antes de atualizar, pare os processos ativos, faça o backup e leia as notas da release no GitHub. O procedimento da documentação é este:

cd /path/to/paperless

docker compose down

docker compose pull

docker compose up

O docker compose up aplica as migrações do banco. Quando tudo estiver certo, pare com CTRL+C e suba de novo em segundo plano, com docker compose up -d.

O Compose oficial usa a imagem com a etiqueta latest. Para ficar numa série específica, troque latest pela etiqueta desejada, como ghcr.io/paperless-ngx/paperless-ngx:1.7, o exemplo da documentação. Se você sai de uma versão anterior para a v3, leia o arquivo migration-v3.md antes, porque a v3 traz mudanças que quebram a compatibilidade, e a atualização para a v3 apaga o histórico de tarefas.

Resumo da instalação

  • Leia o aviso do projeto sobre servidor não confiável.
  • Troque a PAPERLESS_SECRET_KEY e a senha do banco.
  • Defina PAPERLESS_OCR_LANGUAGES=por e PAPERLESS_OCR_LANGUAGE=por.
  • Coloque um proxy com HTTPS na frente e ajuste a PAPERLESS_URL.
  • Agende o document_exporter e teste a restauração.

Antes de escolher o servidor

Vale conhecer as opções de VPS para decidir onde a instalação vai ficar.

Com que servidor você conta hoje para os seus projetos? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Conhecer as VPS

Perguntas frequentes

O Paperless-ngx é gratuito?

O software é de código aberto, sob a GNU General Public License versão 3. O custo está no servidor e no seu tempo para manter a instalação.

Os documentos ficam criptografados?

Segundo o README do projeto, não: as informações ficam armazenadas em texto puro, sem criptografia, e por isso o projeto avisa para não rodar o Paperless-ngx num host não confiável.

O Paperless-ngx lê documentos em português?

Lê, mas o idioma não vem instalado. Defina PAPERLESS_OCR_LANGUAGES=por e PAPERLESS_OCR_LANGUAGE=por.

Como faço backup do Paperless-ngx?

Use o document_exporter, com docker compose exec -T webserver document_exporter ../export, ou copie os volumes do Docker.

Esta resposta lhe foi útil?

Artigos Relacionados