Como Hospedar Paperclip de Forma Autônoma em um VPS (Guia Passo a Passo 2026)

Paperclip é um dos sistemas de gerenciamento de documentos autônomos mais limpos disponíveis. Ele funciona como um contêiner Docker único, armazena arquivos em um volume local e expõe uma interface web na porta 8080. Este guia orienta você por uma instalação completa, pronta para produção, em um VPS Linux - desde a provisão do servidor até o seu primeiro upload de documento.

Pré-requisitos

Um VPS rodando Ubuntu 22.04 LTS ou Debian 12 (recomendado)
Pelo menos 1 vCPU, 1GB de RAM, 20GB de armazenamento (2GB de RAM recomendados para OCR)
Acesso root ou sudo via SSH
Um domínio ou subdomínio apontado para o IP do seu VPS (opcional, mas recomendado para HTTPS)

Opções de VPS recomendadas:

Hetzner Cloud CX22 - €4,15/mês, 2 vCPU, 4GB RAM, 40GB NVMe
Contabo VPS S - €5,99/mês, 4 vCPU, 8GB RAM, 200GB NVMe

Passo 1: Atualizar seu Servidor

apt update && apt upgrade -y

Passo 2: Instalar Docker

curl -fsSL https://get.docker.com | sh
systemctl enable docker
systemctl start docker

Verifique se o Docker está em execução:

docker --version

Passo 3: Instalar Docker Compose

apt install docker-compose-plugin -y
docker compose version

Passo 4: Criar um Diretório de Trabalho

mkdir -p /opt/paperclip && cd /opt/paperclip

Passo 5: Criar o arquivo docker-compose.yml

nano /opt/paperclip/docker-compose.yml

Cole a seguinte configuração:

version: "3.8"

services:
  paperclip:
    image: paperclip/paperclip:latest
    container_name: paperclip
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - paperclip_data:/data
    environment:
      - PAPERCLIP_SECRET_KEY=troque_por_uma_secreta_aleatoria
      - PAPERCLIP_OCR_ENABLED=true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  paperclip_data:

Importante: Substitua troque_por_uma_secreta_aleatoria por uma string aleatória. Gere uma com:

openssl rand -hex 32

Passo 6: (Opcional) Usar PostgreSQL ao invés do SQLite

Para uso multiusuário ou em produção, estenda o arquivo compose:

version: "3.8"

services:
  db:
    image: postgres:16-alpine
    container_name: paperclip_db
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperclip
      POSTGRES_USER: paperclip
      POSTGRES_PASSWORD: senha_forte
    volumes:
      - pg_data:/var/lib/postgresql/data

  paperclip:
    image: paperclip/paperclip:latest
    container_name: paperclip
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "8080:8080"
    volumes:
      - paperclip_data:/data
    environment:
      - PAPERCLIP_SECRET_KEY=sua_secreta_aleatoria
      - PAPERCLIP_DB_HOST=db
      - PAPERCLIP_DB_NAME=paperclip
      - PAPERCLIP_DB_USER=paperclip
      - PAPERCLIP_DB_PASSWORD=senha_forte
      - PAPERCLIP_OCR_ENABLED=true

volumes:
  paperclip_data:
  pg_data:

Passo 7: Iniciar o Paperclip

cd /opt/paperclip
docker compose up -d

Verifique se o contêiner foi iniciado corretamente:

docker compose ps
docker compose logs -f paperclip

Passo 8: Configurar um Firewall

ufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable

Observação: A porta 8080 não é exposta diretamente - iremos fazer um proxy com Caddy/Nginx usando HTTPS.

Passo 9: Configurar HTTPS com Caddy

apt install caddy -y

Edite o arquivo do Caddy:

nano /etc/caddy/Caddyfile

docs.seudominio.com {
    reverse_proxy localhost:8080
}

Recarregue o Caddy:

systemctl reload caddy

O Caddy automaticamente provisiona um certificado Let’s Encrypt.

Acesse https://docs.seudominio.com (ou http://SEU_IP_VPS:8080 se não tiver domínio)
Complete o assistente de configuração inicial - defina seu email e senha de administrador
Faça o upload do seu primeiro documento
Ative o OCR se precisar de busca por texto completo em arquivos digitalizados

Passo 11: Configurar backups

Faça backup do volume Docker para sua máquina local ou um bucket compatível com S3:

# Backup para arquivo local
docker run --rm \
  -v paperclip_data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/paperclip-backup-$(date +%Y%m%d).tar.gz /data

Agende isso com um cron job:

crontab -e
# Adicione:
0 3 * * * /opt/paperclip/backup.sh

Resolução de Problemas

Problema	Solução
Container sai imediatamente	Verifique os logs: `docker compose logs paperclip`
OCR não funciona	Verifique se `PAPERCLIP_OCR_ENABLED=true` e se o container tem memória suficiente
Não consegue acessar a interface	Confirme se a porta 8080 não está bloqueada; verifique `docker compose ps`
Processamento lento de documentos	OCR exige CPU intensiva - considere atualizar para 2+ vCPU se necessário

Para recomendações de provedores de VPS, consulte o melhor VPS para Paperclip ou a comparação completa de VPS.

Como Hospedar Paperclip de Forma Autônoma em um VPS (Guia Passo a Passo 2026)