Installare LogicalDOC su Ubuntu 22.04 o 20.04 Server

LogicalDOC su Ubuntu Server si installa senza troppi fronzoli, ma conviene trattarlo come un servizio applicativo vero: Java, servlet container, database, storage persistente, reverse proxy e backup. Se salti uno di questi pezzi, il risultato è spesso un’installazione che parte ma poi si rompe al primo riavvio, al primo aggiornamento o quando il disco si riempie.

Qui l’obiettivo è mettere in piedi LogicalDOC su Ubuntu 22.04 o 20.04 in modo ripetibile, con una configurazione pulita e con i punti deboli già sotto controllo. L’approccio che seguo è quello più lineare per un server Linux classico: Tomcat dedicato, database separato, directory dati fuori dalla home dell’utente, proxy HTTP(S) davanti e backup ragionato del database e dei file allegati.

Scelta architetturale: non installarlo “alla leggera”

LogicalDOC è un document management system che vive bene quando ha tre cose chiare: un runtime Java coerente, un database affidabile e uno spazio disco prevedibile. Su Ubuntu 20.04 e 22.04 la scelta più semplice è Tomcat 9 con una Java supportata dalla release del prodotto che stai installando. La compatibilità esatta dipende dalla versione di LogicalDOC: prima di partire verifica sempre la matrice ufficiale del vendor per Java e Tomcat, perché non tutte le edizioni si comportano allo stesso modo.

In pratica, il flusso corretto è questo: prepari il database, installi Java, crei un utente dedicato, deployi il WAR o il bundle applicativo, configuri i path di storage e metti davanti un reverse proxy. È il modo più noioso, ma anche quello che ti evita di dover ricostruire tutto dopo un upgrade del sistema o un restore.

Prerequisiti minimi su Ubuntu 20.04 e 22.04

Serve un server aggiornato, con accesso root o sudo, almeno 4 GB di RAM per un uso leggero e spazio disco dimensionato sui documenti reali, non sul minimo teorico. Per test o piccoli team puoi partire con meno, ma Tomcat, il database e l’indicizzazione dei documenti consumano memoria in modo non banale.

Prima di installare tutto, porta il sistema in uno stato noto:

sudo apt update && sudo apt -y upgrade

Se il server è già in produzione per altro, valuta il blast radius: l’installazione di Java, Tomcat e del database può toccare porte, policy firewall e consumo RAM. Il rollback, in caso di problemi, è semplice solo se hai snapshot o backup della macchina e del database.

Database: MySQL o MariaDB, ma con un utente dedicato

LogicalDOC lavora bene con MySQL o MariaDB. Su Ubuntu conviene restare su MariaDB quando non hai vincoli di compatibilità specifici, perché l’installazione è lineare e l’integrazione con il sistema è pulita. Se invece il tuo stack usa già MySQL, non ha senso introdurre un motore diverso solo per questo servizio.

Installa il database e crea schema e utente dedicati. Non usare account generici, non riutilizzare credenziali di altri servizi e non lasciare il database esposto su tutte le interfacce se non serve.

sudo apt install -y mariadb-server

Poi entra nel client SQL e crea tutto con privilegi limitati sul solo database dell’applicazione:

sudo mysql

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

La password va gestita fuori dal testo e fuori dai ticket. Se devi passare questa configurazione a un team, usa un secret manager o un file protetto con permessi stretti, non una nota condivisa.

Java e Tomcat: il binomio che determina la stabilità

Su Ubuntu 22.04 la scelta tipica è una Java LTS supportata dalla tua versione di LogicalDOC. Il punto non è solo “installare Java”, ma installare la versione giusta e non mischiarla con altre presenti sulla macchina. Se hai più runtime, Tomcat potrebbe partire con quello sbagliato e il problema si vede solo a runtime, magari come errore di classe o comportamento anomalo del motore di ricerca interno.

Installa Tomcat e una Java coerente con la release che stai deployando. Il pacchetto esatto può variare in base al repository disponibile, ma il concetto resta identico:

sudo apt install -y default-jdk tomcat9

Verifica subito quale Java sta vedendo il sistema:

java -version
sudo systemctl status tomcat9 --no-pager

Se LogicalDOC richiede una Java specifica, imposta `JAVA_HOME` nel file di servizio o nell’ambiente di Tomcat, non “a mano” in una shell temporanea. Altrimenti al primo reboot perdi la configurazione.

Utente dedicato, directory dati e permessi

Non far girare l’app come root. Crea un utente di servizio e prepara directory separate per binari, dati e log. Il risultato è più manutenibile e ti semplifica backup e ripristino.

sudo adduser --system --group --home /opt/logicaldoc logicaldoc
sudo mkdir -p /opt/logicaldoc /var/lib/logicaldoc /var/log/logicaldoc
sudo chown -R logicaldoc:logicaldoc /opt/logicaldoc /var/lib/logicaldoc /var/log/logicaldoc

La logica è semplice: i binari o il WAR stanno sotto `/opt/logicaldoc`, i dati persistenti sotto `/var/lib/logicaldoc` e i log sotto `/var/log/logicaldoc`. Se il prodotto offre un path configurabile per repository documentale, indirizzalo verso `/var/lib/logicaldoc` o una mount dedicata, non verso un path volatile.

Se il server è in produzione, valuta anche una partizione o un volume separato per i documenti. Quando il repository cresce, il rischio principale non è il crash immediato, ma il filesystem pieno che poi manda in crisi database, log e servizi di sistema.

Deploy dell’applicazione LogicalDOC

La distribuzione può arrivare come WAR, come bundle Tomcat o come pacchetto del vendor. Il punto operativo è sempre lo stesso: devi far sì che Tomcat veda l’applicazione e che i file di configurazione persistano fuori dal content root, altrimenti ogni aggiornamento sovrascrive tutto.

Se hai un file WAR, il deploy base su Tomcat è lineare:

sudo cp logicaldoc.war /var/lib/tomcat9/webapps/

Controlla i log di deploy appena copiato il file:

sudo journalctl -u tomcat9 -f

Se il prodotto richiede un file di configurazione esterno, tienilo versionato e separato dal pacchetto applicativo. Un approccio prudente è avere una copia di backup del file prima di ogni modifica:

sudo cp /percorso/del/file.conf /percorso/del/file.conf.$(date +%F).bak

Questa banalità salva tempo quando devi tornare indietro dopo una modifica errata a JDBC URL, path documentale o parametri di memoria.

Configurazione database e connessione JDBC

Il cuore del setup è la connessione tra LogicalDOC e il database. Qui gli errori tipici sono tre: hostname sbagliato, credenziali errate e charset non coerente. Il primo si vede subito, il secondo produce errori di autenticazione, il terzo emerge dopo con problemi su caratteri speciali, metadati e contenuti indicizzati.

Usa un URL JDBC coerente con il tuo motore. Un esempio generico per MariaDB/MySQL è del tipo:

jdbc:mysql://127.0.0.1:3306/logicaldoc?useUnicode=true&characterEncoding=utf8&useSSL=false

Se il vendor o la versione dell’app richiedono parametri diversi, adegua la stringa senza inventare opzioni non supportate. Quando possibile, imposta `127.0.0.1` invece di `localhost` se vuoi evitare ambiguità con socket e risoluzione locale.

Per verificare il database prima ancora di aprire l’interfaccia web, controlla che il servizio risponda e che l’utente abbia davvero accesso:

mysql -u logicaldoc -p -h 127.0.0.1 logicaldoc -e 'SHOW TABLES;'

Se il comando fallisce, non andare avanti a tentativi: risolvi prima la connettività e i permessi, poi il deploy applicativo.

Reverse proxy con Nginx e TLS

Esporre Tomcat direttamente su Internet è una scelta debole. Meglio mettergli davanti Nginx, terminare TLS lì e lasciare Tomcat in ascolto solo su localhost o su una rete interna. In questo modo riduci la superficie d’attacco, semplifichi la gestione dei certificati e puoi applicare limiti, header e regole di caching dove serve.

Un blocco minimo Nginx può essere questo:

server { listen 80; server_name docs.example.com; return 301 https://$host$request_uri;
} server { listen 443 ssl http2; server_name docs.example.com; ssl_certificate /etc/letsencrypt/live/docs.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/docs.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; proxy_read_timeout 300; }
}

Dopo la modifica, testa la sintassi e ricarica il servizio:

sudo nginx -t
sudo systemctl reload nginx

Se usi Let’s Encrypt, verifica la scadenza e il rinnovo automatico. Un certificato scaduto su un DMS sembra un problema banale, ma blocca l’accesso degli utenti e spesso viene scoperto solo quando il browser inizia a rifiutare la connessione.

Memoria, upload e limiti operativi

LogicalDOC non è un’app “leggera” nel senso classico. L’indicizzazione, le preview e gli upload possono saturare RAM e CPU se lasci i valori di default senza guardare il carico reale. Il primo numero che guardo sempre è la memoria heap di Tomcat e poi il comportamento del database sotto carico, non il contrario.

Se noti OOM o riavvii di Tomcat, controlla i log di sistema e l’heap configurato. I punti di verifica sono questi:

sudo journalctl -u tomcat9 --since today
sudo dmesg -T | grep -i oom

Se il server ha poca RAM, aumenta la memoria solo dopo aver escluso leak o configurazioni errate. Non è raro che il problema sia un upload eccessivo o un’operazione batch lasciata in esecuzione, non la dimensione dell’heap in sé.

Per gli upload grandi, verifica anche i limiti di Nginx e Tomcat. Il reverse proxy può troncare richieste troppo grandi prima che arrivino all’applicazione, mentre Tomcat può avere limiti su multipart e timeout. Se il caricamento fallisce, non fermarti all’errore visibile: controlla anche il log applicativo e quello del proxy.

Primo avvio e verifica funzionale

Dopo il deploy, il test non è solo “la pagina si apre”. Devi verificare almeno tre cose: l’interfaccia web risponde, il login funziona e un documento di prova viene caricato e ritrovato nella ricerca. Se una di queste manca, hai un’installazione parziale, non un sistema pronto.

Controlli minimi:

curl -I https://docs.example.com

Se il risultato è un 200 o un redirect atteso, la parte web è in piedi. Se ricevi 502, 503 o timeout, il problema è più a valle: Tomcat fermo, app non deployata, proxy mal configurato o porta sbagliata.

Backup e ripristino: il punto che molti rimandano

Un DMS senza backup serio è fragile per definizione. Devi salvare almeno il database e il repository documentale. Se LogicalDOC usa metadati, workflow e allegati separati, i due pezzi devono restare coerenti nello stesso punto temporale.

Per il database usa un dump consistente, ad esempio:

mysqldump -u root -p --single-transaction logicaldoc > logicaldoc.sql

Per i file, usa un archivio o uno strumento di sincronizzazione che preservi permessi e timestamp. Se il repository è grande, meglio un backup incrementale o snapshot del volume. Il restore va testato, non solo immaginato.

In un ambiente serio, il piano minimo è: backup giornaliero del database, snapshot del volume documentale, retention definita e una prova di ripristino periodica su macchina di test. Senza questa verifica, il backup è solo un file che speri di non dover usare.

Hardening minimo senza complicarsi la vita

La superficie d’attacco di una installazione documentale non è trascurabile: upload, autenticazione, webapp Java e, spesso, integrazioni con LDAP o mail. Tieni il servizio esposto solo dove serve, limita l’accesso amministrativo e aggiorna con regolarità i pacchetti di sistema e l’applicazione stessa.

Le misure minime che hanno senso davvero sono queste:

Se integri autenticazione esterna, testa prima su un ambiente di prova. Un errore di LDAP o SSO può bloccare l’accesso amministrativo e complicare il recupero, soprattutto se non hai un account locale di emergenza.

Quando qualcosa non torna: sintomi rapidi e lettura pratica

Se la pagina non si apre, parti dal layer più esterno: DNS, proxy, Tomcat e infine database. Se vedi una pagina bianca o errori applicativi, vai subito ai log di Tomcat e dell’applicazione. Se il login fallisce ma l’app è viva, controlla database, sessioni e autenticazione. Se gli upload si bloccano, guarda prima proxy e limiti di dimensione, poi spazio disco e permessi.

Il comando più utile, in questi casi, è quasi sempre lo stesso: leggere i log con ordine e senza saltare ai cambiamenti. Una modifica alla cieca su timeout, heap o DB URL può peggiorare il quadro e rendere più difficile capire dov’era il guasto iniziale.

In sintesi operativa, una installazione solida di LogicalDOC su Ubuntu 20.04 o 22.04 non richiede magie: richiede disciplina. Se tieni separati runtime, database, repository e proxy, poi gestisci backup e aggiornamenti con metodo, il sistema resta leggibile anche dopo mesi. Ed è proprio questo il valore, in produzione: non solo far partire l’app, ma farla restare gestibile.