Come Ospitare Paperclip su un VPS in Autonomia (Guida 2026)

Come Ospitare Paperclip su un VPS in Autonomia (Guida 2026)

Paperclip è uno dei sistemi di gestione documentale self-hosted più puliti disponibili. Gira come singolo container Docker, archivia i file su un volume locale ed espone un’interfaccia web sulla porta 8080. Questa guida ti accompagna in un’installazione completa e pronta per la produzione su un VPS Linux — dall’acquisto del server al primo documento caricato.

Prerequisiti

• Un VPS con Ubuntu 22.04 LTS o Debian 12 (consigliato)
• Almeno 1 vCPU, 1 GB di RAM, 20 GB di storage (2 GB di RAM consigliati per OCR)
• Accesso root o sudo via SSH
• Un dominio o sottodominio che punta all’IP del VPS (opzionale ma consigliato per HTTPS)

Opzioni VPS consigliate:

• Hetzner Cloud CX22 — 4,15 €/mese, 2 vCPU, 4 GB di RAM, 40 GB NVMe
• Contabo VPS S — 5,99 €/mese, 4 vCPU, 8 GB di RAM, 200 GB NVMe

Passo 1: Aggiornare il server

apt update && apt upgrade -y

Passo 2: Installare Docker

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

Verificare che Docker funzioni:

docker --version

Passo 3: Installare Docker Compose

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

Passo 4: Creare una directory di lavoro

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

Passo 5: Creare un docker-compose.yml

nano /opt/paperclip/docker-compose.yml

Incolla la seguente configurazione:

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=sostituisci_con_una_chiave_casuale
      - PAPERCLIP_OCR_ENABLED=true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  paperclip_data:

Importante: sostituisci sostituisci_con_una_chiave_casuale con una stringa casuale. Generane una con:

openssl rand -hex 32

Passo 6: (Opzionale) Usare PostgreSQL invece di SQLite

Per uso multi-utente o in produzione, estendi il file 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: password_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=la_tua_chiave_casuale
      - PAPERCLIP_DB_HOST=db
      - PAPERCLIP_DB_NAME=paperclip
      - PAPERCLIP_DB_USER=paperclip
      - PAPERCLIP_DB_PASSWORD=password_forte
      - PAPERCLIP_OCR_ENABLED=true

volumes:
  paperclip_data:
  pg_data:

Passo 7: Avviare Paperclip

cd /opt/paperclip
docker compose up -d

Verificare che il container sia avviato:

docker compose ps
docker compose logs -f paperclip

Passo 8: Configurare il firewall

ufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable

Nota: la porta 8080 non viene esposta direttamente — il traffico passerà attraverso Caddy/Nginx con HTTPS.

Passo 9: Configurare HTTPS con Caddy

apt install caddy -y

Modificare il Caddyfile:

nano /etc/caddy/Caddyfile

docs.tuodominio.it {
    reverse_proxy localhost:8080
}

Ricaricare Caddy:

systemctl reload caddy

Caddy provvede automaticamente al certificato Let’s Encrypt.

Passo 10: Primo accesso

1. Apri https://docs.tuodominio.it (o http://IP_DEL_TUO_VPS:8080 senza dominio)
2. Completa la procedura guidata di configurazione iniziale — imposta email e password admin
3. Carica il primo documento
4. Abilita OCR se hai bisogno della ricerca full-text sui file scansionati

Passo 11: Configurare i backup

Esegui il backup del volume Docker in locale o su un bucket compatibile S3:

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

Pianificare con cron:

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

Risoluzione dei problemi

Per i consigli sui provider VPS, consulta il miglior VPS per Paperclip o il confronto VPS completo.