DocWebGestione documentale self-hosted

Guida

Installazione

DocWeb gira su un NAS Synology o su un normale server web. Scegli la via adatta al tuo ambiente – i passaggi per gli strumenti OCR e la configurazione dopo l'installazione valgono per entrambe.

Contenuto

  1. Requisiti
  2. Via A: NAS Synology (DSM)
  3. Via B: server web standard
  4. Configurare gli strumenti OCR
  5. Dopo l'installazione
  6. Se qualcosa non funziona
  7. Accesso

1. Requisiti

DocWeb è volutamente parco: nessuna dipendenza da framework, niente Node.js, nessuna fase di compilazione. Ti servono essenzialmente un server web con PHP e un database.

Indispensabile

  • PHP 8.x (testato con 8.2) con le estensioni pdo_mysql, mbstring, zip, zlib, json
  • MariaDB 10 (o MySQL con le stesse funzioni), set di caratteri utf8mb4
  • Apache o nginx – oppure Web Station su un Synology
  • Permessi di scrittura dell'utente del server web nella cartella del progetto (per .env, documents/, inbox/, trash/)

Opzionale – per la ricerca full-text nei documenti scansionati

  • Tesseract (OCR per pagine scansionate e immagini)
  • Poppler (pdftotext, pdftoppm)
  • shell_exec deve essere consentito sul server perché gli strumenti possano essere richiamati
Senza questi strumenti DocWeb funziona comunque. Il testo incorporato nei PDF viene letto anche senza Poppler (fallback in PHP puro) e i file Office vengono analizzati tramite l'estensione zip. Solo i PDF scansionati e le immagini restano quindi senza full-text – nome del file, categoria e tag restano comunque ricercabili.
Spazio necessario: DocWeb non salva i documenti due volte. Occorrono i documenti, una cache testuale (indice di ricerca) e il database. A seconda dell'archivio la cache testuale richiede spazio aggiuntivo.

Via A

2. NAS Synology (DSM, Web Station)

La via consigliata se DocWeb deve girare sulla tua rete, su un Synology. L'accesso è allora tipicamente possibile solo sulla rete locale o tramite VPN.

  1. Installare Web Station, PHP 8 e MariaDB

    Nel Centro pacchetti del Synology installare i pacchetti Web Station, PHP 8.x e MariaDB 10. Poi, sotto Web Station → Server web, creare un server web con PHP 8 se non ne esiste ancora uno.

  2. Mettere i file dell'app nella directory web

    Copiare l'intera cartella del progetto in /volume1/web/docweb – quindi la cartella che contiene public/, src/ e sql/. Le cartelle documents/, inbox/ e trash/ vengono create automaticamente durante l'installazione.

  3. Creare il database

    Tramite phpMyAdmin (o via SSH) creare un database con il relativo utente: 

    CREATE DATABASE docweb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'docweb'@'localhost' IDENTIFIED BY 'DEIN_PASSWORT';
GRANT ALL PRIVILEGES ON docweb.* TO 'docweb'@'localhost';
FLUSH PRIVILEGES;

  4. Creare il file di configurazione .env

    Nella cartella del progetto (un livello sopra public/) creare un file .env: 

    DB_HOST=localhost
DB_PORT=3307
DB_NAME=docweb
DB_USER=docweb
DB_PASSWORD=DEIN_PASSWORT
    Porta: Il pacchetto MariaDB di Synology è in ascolto di default sulla porta 3307, non sulla 3306. Per un database esterno adattare di conseguenza.

  5. Eseguire l'installazione

    Aprire http://NAS-ADRESSE/docweb/install.php nel browser e compilare il modulo. L'assistente crea tutte le tabelle, scrive le credenziali in .env, crea le cartelle e imposta il primo account amministratore.

    In alternativa, via SSH nella cartella del progetto: php install.php. Senza --admin-pass viene generata una password casuale e mostrata una sola volta.

    Poi eliminare install.php. L'assistente si rifiuta di funzionare non appena esiste un account utente – ciò nonostante non ha motivo di restare a lungo sul server.

  6. Controllare le impostazioni PHP

    Sotto Web Station → Linguaggi di script → PHP 8.x → Configurazione:

    • shell_exec non deve essere elencata in disable_functions (altrimenti niente OCR)
    • Attivare le estensioni: pdo_mysql, mbstring, zip, zlib, json

  7. Installare gli strumenti OCR (opzionale)

    Per i documenti scansionati configurare Tesseract e Poppler – le istruzioni sono nella Configurare gli strumenti OCR. Senza questo passaggio DocWeb funziona, ma senza full-text nelle scansioni.

  8. Accedere ed eseguire la sincronizzazione

    Accedere sotto http://NAS-ADRESSE/docweb/ e fare clic su Sync nella barra superiore. Poi eseguire una volta Reindex se gli strumenti OCR sono stati configurati – così vengono rilevate anche le scansioni già presenti.

Ordine con un archivio già esistente: Prima mettere i documenti nella cartella dei documenti, poi eseguire la sincronizzazione. Con moltissimi file la prima passata dura di conseguenza – prosegue in background con indicazione del progresso.

Via B

3. Server web standard (Apache o nginx)

Per un server noleggiato, una macchina propria o una macchina virtuale. Così DocWeb diventa raggiungibile anche dall'esterno – presta quindi particolare attenzione alle note di sicurezza alla fine di questa sezione.

  1. Installare PHP e il database

    Su Debian o Ubuntu bastano pochi pacchetti: 

    sudo apt install apache2 mariadb-server php php-mysql php-mbstring \
     php-zip php-gd php-curl libapache2-mod-php

sudo mysql_secure_installation

    Per nginx al posto di Apache installare gli stessi pacchetti PHP con php-fpm.

  2. Caricare la cartella del progetto

    Copiare l'intera cartella del progetto sul server. Collocala all'esterno della directory accessibile pubblicamente e fai puntare il dominio alla sottocartella public/: 

    /var/www/docweb/            <- cartella del progetto (non pubblica)├── public/                 <- qui punta il dominio├── src/
├── sql/
├── documents/
├── inbox/
└── trash/
    Questa è la configurazione consigliata. Così codice sorgente, configurazione e documenti stanno fuori dal web e non possono essere scaricati direttamente.

    Per Apache, per esempio: 

    <VirtualHost *:443>
    ServerName docweb.example.ch
    DocumentRoot /var/www/docweb/public

    <Directory /var/www/docweb/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

    In alternativa la cartella del progetto stessa può essere la directory web – l'applicazione si trova allora sotto /public/ ed è raggiungibile per esempio via https://example.ch/public/. Anche questa configurazione è supportata; la prima variante è però più pulita.

  3. Creare il database

    sudo mysql -e "CREATE DATABASE docweb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
sudo mysql -e "CREATE USER 'docweb'@'localhost' IDENTIFIED BY 'DEIN_PASSWORT';"
sudo mysql -e "GRANT ALL PRIVILEGES ON docweb.* TO 'docweb'@'localhost'; FLUSH PRIVILEGES;"

  4. Creare il file di configurazione .env

    Nella cartella del progetto (un livello sopra public/): 

    DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=docweb
DB_USER=docweb
DB_PASSWORD=DEIN_PASSWORT

  5. Impostare i permessi dei file

    L'utente del server web (su Debian/Ubuntu www-data) deve poter scrivere nella cartella del progetto – per .env e le cartelle documents/, inbox/ e trash/: 

    sudo chown -R www-data:www-data /var/www/docweb
sudo find /var/www/docweb -type d -exec chmod 750 {} \;
sudo find /var/www/docweb -type f -exec chmod 640 {} \;

  6. Eseguire l'installazione

    Aprire https://docweb.example.ch/install.php nel browser e compilare il modulo. Poi eliminare install.php.

    Nessun accesso SSH? L'assistente lavora interamente nel browser – non serve alcuno strumento da riga di comando. Anche l'esercizio corrente ne fa a meno (vedi il passo successivo).

  7. Eseguire la prima sincronizzazione

    Dopo l'accesso fare clic su Sync nella barra superiore. Come procede la sincronizzazione dipende dalla possibilità di avviare un PHP da riga di comando sul server:

    • Con PHP da riga di comando: La sincronizzazione gira come processo in background. Se è affidabile non c'è altro da fare. Se il tuo server ha il binario PHP in un punto insolito, indicane il percorso in .env: PHP_CLI=/usr/bin/php
    • Senza PHP da riga di comando (tipico nell'hosting condiviso, quando shell_exec o popen sono bloccati): DocWeb passa automaticamente alla variante web e svolge la sincronizzazione a piccoli passi tramite il server web. La barra di stato mostra allora l'avviso di lasciare aperta la finestra – l'operazione continua finché la pagina resta aperta. Se viene chiusa, la visita successiva riprende dall'ultimo stato.
    Adattare la lunghezza dei passi: Se la variante web si interrompe con un errore di timeout, impostare in .env un valore più piccolo, per esempio WEB_WORKER_BUDGET=10 (secondi per passo).

  8. Sicurezza con accesso pubblico

    • Usare HTTPS – con Let's Encrypt o un certificato proprio
    • Far puntare il dominio a public/ (vedi passo 2), così che src/, documents/ e .env non siano raggiungibili dal web
    • Se lo desideri, collocare la cartella dei documenti fuori dalla cartella del progetto – impostare a tal fine DOCS_ROOT in .env, per esempio DOCS_ROOT=/srv/documenti
    • Attivare l'accesso a due fattori per gli account utente
    • Configurare backup regolari (DocWeb crea uno ZIP di database e documenti)

Full-text nelle scansioni

4. Configurare gli strumenti OCR

Questi strumenti sono opzionali. Senza di essi la ricerca non trova testo nelle pagine scansionate e nelle immagini. Con essi il contenuto viene riconosciuto e diventa ricercabile.

Su un server web standard

Tesseract e Poppler arrivano dal gestore di pacchetti, insieme ai dati linguistici: 

sudo apt install tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng \
     tesseract-ocr-fra tesseract-ocr-ita poppler-utils

Poi verificare che gli strumenti vengano trovati: 

which pdftotext pdftoppm tesseract
tesseract --list-langs

Su un NAS Synology

I vecchi pacchetti per Tesseract e Poppler non sono più disponibili per le versioni recenti di DSM. Due vie funzionano: Entware (binari direttamente sul file system, consigliato) oppure un Docker-Container che mette a disposizione i binari tramite una cartella.

Variante 1: Entware (consigliato)

Prima accedere via SSH come admin e diventare root con sudo -i. Attivare SSH in precedenza sotto Pannello di controllo → Terminale e SNMP. 

# Creare una directory persistente (sopravvive agli aggiornamenti DSM)
mkdir -p /volume1/@Entware/opt
mount -o bind /volume1/@Entware/opt /opt

# Installare Entware – scegliere l'URL adatto all'architettura della CPU
# x86_64 (p. es. RS1221RP):
wget -O - https://bin.entware.net/x64-k3.2/installer/generic.sh | /bin/sh
# ARMv8 (p. es. DS920+):
# wget -O - https://bin.entware.net/aarch64-k3.10/installer/generic.sh | /bin/sh

Poi installare i pacchetti: 

/opt/bin/opkg update
/opt/bin/opkg install tesseract tesseract-data-eng poppler-utils
Importante: Il pacchetto si chiama poppler-utils, non poppler. In Entware non esiste un pacchetto di lingua tedesca – deu va installato a mano. 
cd /opt/share/tessdata
wget -O deu.traineddata https://raw.githubusercontent.com/tesseract-ocr/tessdata/main/deu.traineddata
/opt/bin/tesseract --list-langs   # "deu" deve comparire

I binari si trovano poi sotto /opt/bin/. Se non vengono trovati automaticamente, indicarli in .env: 

PDFTOTEXT_PATH=/opt/bin/pdftotext
PDFTOPPM_PATH=/opt/bin/pdftoppm
TESSERACT_PATH=/opt/bin/tesseract

Perché gli strumenti sopravvivano a un riavvio del NAS, inserire lo script fornito nel Utilità di pianificazione (Pannello di controllo → Utilità di pianificazione → Attività attivate, trigger «All'avvio», utente root): 

/bin/sh /volume1/web/docweb/scripts/entware_boot.sh

Lo script rimonta /opt, reinstalla Entware e i pacchetti se necessario e si occupa dei dati linguistici OCR.

Variante 2: container Docker

Un container mette a disposizione i binari tramite una cartella condivisa: 

docker run -d --name ocr-tools \
  -v /volume1/web/docweb/tools:/tools \
  debian:bookworm-slim \
  bash -c "apt-get update && apt-get install -y tesseract-ocr tesseract-ocr-deu \
           tesseract-ocr-eng poppler-utils && \
           cp /usr/bin/tesseract /usr/bin/pdftotext /usr/bin/pdftoppm /tools/ && sleep infinity"

Poiché i file non sono nel percorso di ricerca, impostare i percorsi in .env: 

PDFTOTEXT_PATH=/volume1/web/docweb/tools/pdftotext
PDFTOPPM_PATH=/volume1/web/docweb/tools/pdftoppm
TESSERACT_PATH=/volume1/web/docweb/tools/tesseract

Controllare lo stato

Dopo l'accesso il menu utente in alto a destra indica se i tre strumenti sono stati trovati: pdftotext (testo dei PDF), pdftoppm (rendering delle pagine) e tesseract (OCR).

Scansioni già presenti: Dopo la configurazione eseguire una volta Reindex nella barra superiore. Solo così il full-text di tutti i documenti esistenti viene ricostruito.

5. Dopo l'installazione

Primi passi

  • Accesso: tramite Accesso o direttamente sotto https://docweb.gregus.ch/.
  • Cambiare la password: cambiare la password amministratore scelta in fase di configurazione dopo il primo accesso.
  • Creare altri utenti: i ruoli amministratore, editor e lettura stabiliscono chi può vedere e modificare i documenti.
  • Accesso a due fattori: consigliato per gli account accessibili dall'esterno.
  • Controllare la cartella dei documenti: controllare la posizione di archiviazione sotto Impostazioni → Database – può essere modificata anche in seguito, la sincronizzazione successiva adotta la nuova posizione.
  • Eseguire la sincronizzazione: legge la cartella dei documenti ed elabora solo i file nuovi, modificati ed eliminati.
  • Eseguire il reindex: una volta sola, dopo aver configurato Tesseract e Poppler.

Inserire documenti nell'archivio

  • Direttamente nella cartella: mettere i file nella cartella dei documenti tramite file manager, SMB o sincronizzazione cloud, poi eseguire la sincronizzazione. La struttura delle cartelle diventa le categorie.
  • Tramite l'inbox: le nuove scansioni arrivano prima nell'inbox, lì vengono controllate, ruotate e rinominate, quindi archiviate in una categoria con tag – se manca la categoria giusta, può essere creata direttamente in fase di archiviazione.
  • Scansione in blocco: un intero fascio con fogli separatori viene acquisito in un'unica passata e suddiviso automaticamente in singoli PDF.
  • Archiviazione delle e-mail: scaricare le e-mail via IMAP o POP3 e archiviarle come PDF.
  • Tramite l'app iOS: acquisire documenti con la fotocamera e archiviarli subito.

Backup

DocWeb crea un backup di database e documenti come ZIP. Poiché i documenti esistono comunque come file ordinari, per l'archivio basta anche un salvataggio della cartella dei documenti con i mezzi abituali – per una migrazione completa servono anche il database e .env.

6. Se qualcosa non funziona

«Il server non risponde» oppure una pagina vuota

Il più delle volte manca un'estensione PHP oppure il database non è raggiungibile. Controllare l'output degli errori PHP del server (Apache: error.log, nginx: /var/log/nginx/error.log). Cause frequenti: pdo_mysql mancante, porta sbagliata, password errata in .env.

L'installazione segnala che manca src/config.php

Allora install.php non si trova nella cartella del progetto oppure il livello superiore non contiene src/. Carica la cartella di progetto completa – non solo il contenuto di public/. L'installer riconosce da sé entrambe le disposizioni (cartella del progetto e public/).

Davanti a «Cartella» o «.env» compare una riga rossa

L'utente del server web non può scrivere nella cartella del progetto. Impostare i permessi come al passo 5 (via B). Su un Synology verificare che la cartella condivisa sia scrivibile per l'utente di Web Station.

Dopo la sincronizzazione manca il full-text nelle scansioni

Gli strumenti OCR mancano o non sono richiamabili. Il menu utente mostra lo stato dei tre strumenti. Se mancano tutti e tre, di solito shell_exec è bloccato in disable_functions – oppure i percorsi vanno impostati in .env. Dopo la correzione eseguire una volta Reindex.

I file Word, Excel e PowerPoint non sono ricercabili

Per questo serve l'estensione PHP zip. Attivarla e avviare di nuovo il reindex.

«Non è stato possibile avviare la sincronizzazione» oppure l'operazione si blocca

Sui server senza PHP da riga di comando avviabile subentra automaticamente la variante web (vedi passo 7 della via B). Se il messaggio compare comunque, verificare:

  • JavaScript è attivo nella finestra del browser? Il controllo passa dal browser.
  • Se l'esecuzione si interrompe dopo un po', impostare in .env un valore più piccolo per WEB_WORKER_BUDGET (p. es. 10).
  • Esiste un percorso da riga di comando che potrebbe aiutare in .env? PHP_CLI=/usr/bin/php

L'esecuzione si interrompe quando apro altre pagine

In modalità web è il browser a eseguire i passi di lavoro. Se la pagina viene chiusa, l'operazione si mette in pausa – non si perde nulla. La visita successiva riprende dall'ultimo stato.

Ho dimenticato la password amministratore

L'installer non crea un secondo account quando ne esiste già uno – è voluto. Reimposta la password direttamente nel database oppure crea un nuovo utente con ruolo amministratore tramite phpMyAdmin.