Installare Apache Solr su Debian 12 passo dopo passo

Apache Solr su Debian 12: scelta architetturale e prerequisiti

Solr gira sopra Java e, in produzione, va trattato come un servizio applicativo a tutti gli effetti: non basta installarlo, serve verificare runtime, porta di ascolto, persistenza dei dati e avvio automatico. Su Debian 12 il punto critico non è tanto l’installazione del pacchetto, quanto la compatibilità della versione di Java, la configurazione del servizio systemd e l’esposizione sicura della console di amministrazione.

Per un’installazione pulita ti servono privilegi sudo, accesso shell al server e una rete che consenta il download dei pacchetti. Se il nodo è esposto su Internet, considera da subito l’accesso alla porta 8983 come superficie d’attacco da limitare con firewall o reverse proxy.

Assunzione operativa: Debian 12 recente, systemd attivo, e nessun Solr già in esecuzione sulla macchina.

Verifica iniziale del sistema

Prima di modificare il sistema conviene controllare versione OS, spazio disco e presenza di Java. Solr richiede una JVM compatibile; su Debian 12 la scelta più semplice è OpenJDK 17.

cat /etc/debian_version
uname -a
df -h
java -version

Atteso:

• Debian 12 o derivata compatibile.
• Spazio disco sufficiente in /var e nel filesystem che ospiterà i dati Solr.
• java -version restituisce OpenJDK 17 o equivalente compatibile.

Se java non è presente, installalo prima di andare oltre. Se hai già Java 11 o più vecchio, non forzare Solr senza verificare la compatibilità della release che vuoi usare.

Installare Java su Debian 12

Per una base standard installa OpenJDK 17 dai repository ufficiali. È la strada meno rischiosa e con meno sorprese in fase di aggiornamento.

sudo apt update
sudo apt install -y openjdk-17-jre-headless

Verifica subito il runtime:

java -version

Atteso: output con versione 17.x e architettura coerente con il server. Se il comando non è trovato, controlla la variabile PATH o eventuali alternative gestite da update-alternatives.

Se prevedi di compilare plugin o fare attività di sviluppo, puoi usare openjdk-17-jdk al posto della sola runtime, ma per un nodo Solr di produzione la JRE headless è sufficiente.

Creare utente e directory dedicate

Solr non va eseguito come root. Crea un utente di servizio e una struttura directory separata per binari, dati e log. Questo riduce il rischio operativo e semplifica backup e migrazioni.

sudo useradd --system --home /opt/solr --shell /usr/sbin/nologin solr
sudo mkdir -p /opt/solr /var/solr /var/log/solr
sudo chown -R solr:solr /var/solr /var/log/solr

Se usi una cartella diversa per i dati, mantieni la stessa logica: binari in /opt, dati in /var, log in /var/log. La separazione aiuta anche in caso di restore.

Scaricare Apache Solr

La distribuzione più comune è il tarball ufficiale di Apache. Questo approccio evita dipendenze da repository terzi e ti lascia pieno controllo sulla versione. Sostituisci X.Y.Z con la release che vuoi installare.

cd /tmp
wget https://downloads.apache.org/lucene/solr/X.Y.Z/solr-X.Y.Z.tgz
wget https://downloads.apache.org/lucene/solr/X.Y.Z/solr-X.Y.Z.tgz.sha512

Prima di estrarre, verifica l’hash. È un controllo minimo ma utile per evitare file corrotti o alterati.

sha512sum -c solr-X.Y.Z.tgz.sha512

Atteso: OK. Se fallisce, non procedere con l’estrazione.

Installazione dei binari

Estrai l’archivio e copia i file nella directory definitiva. Evita di far girare Solr direttamente dalla cartella temporanea.

tar xzf solr-X.Y.Z.tgz
sudo cp -r solr-X.Y.Z /opt/solr

In alternativa, se vuoi un layout più pulito, puoi rinominare la directory di versione in /opt/solr solo dopo aver verificato il contenuto. Il punto importante è avere un percorso stabile per il servizio systemd.

Controlla che i binari esistano:

ls -l /opt/solr/bin/solr

Atteso: file eseguibile presente.

Preparare il servizio systemd

Per avviare Solr in modo gestito conviene creare un’unità systemd dedicata. Questo ti dà avvio automatico, restart controllato e integrazione con i log di sistema.

Crea un file come /etc/systemd/system/solr.service con una configurazione minima coerente con i percorsi usati sopra. Esempio concettuale:

[Unit]
Description=Apache Solr
After=network.target

[Service]
Type=forking
User=solr
Group=solr
ExecStart=/opt/solr/bin/solr start -f -p 8983 -s /var/solr
ExecStop=/opt/solr/bin/solr stop -p 8983
Restart=on-failure
RestartSec=10
LimitNOFILE=65000

[Install]
WantedBy=multi-user.target

Nota operativa: la modalità esatta di avvio dipende dalla versione di Solr e dallo script fornito. Se il comando del bundle non corrisponde alla release che hai scaricato, verifica /opt/solr/bin/solr --help prima di applicare l’unità. Non forzare un template senza controllare la sintassi supportata.

Dopo aver creato il file, ricarica systemd:

sudo systemctl daemon-reload
sudo systemctl enable solr

Atteso: nessun errore in reload e servizio abilitato all’avvio.

Avvio e primo controllo del servizio

Avvia Solr e controlla subito lo stato. Qui l’obiettivo è capire se il problema è nel servizio, nella JVM o nella porta di ascolto.

sudo systemctl start solr
sudo systemctl status solr --no-pager

Atteso:

• Stato active (running).
• Nessun crash loop.
• Log iniziali senza errori di binding o permessi.

Se il servizio non parte, guarda i log di systemd:

journalctl -u solr -n 100 --no-pager

Le cause più comuni sono: porta già occupata, permessi sui dati, Java non compatibile, o parametri di avvio errati.

Verificare la porta 8983

La console web di Solr ascolta di default sulla porta 8983. Prima di aprire il firewall, verifica che il processo sia effettivamente in ascolto sulla macchina locale.

ss -ltnp | grep 8983
curl -I http://127.0.0.1:8983/solr/

Atteso: una risposta HTTP valida, spesso 200 o 302 a seconda della versione e del path. Se curl fallisce ma il servizio è attivo, controlla se Solr ascolta solo su localhost o su un indirizzo specifico.

Se vuoi limitare l’esposizione, è normale lasciare Solr in ascolto solo su 127.0.0.1 e pubblicarlo tramite reverse proxy. È una scelta migliore rispetto all’apertura diretta su Internet.

Aprire il firewall in modo controllato

Se hai bisogno di accesso remoto diretto, apri la porta solo da reti fidate. Su Debian potresti usare ufw o regole nftables, a seconda del setup già presente.

sudo ufw allow from 192.0.2.0/24 to any port 8983 proto tcp

Oppure, se non usi UFW, verifica la policy del firewall già in uso prima di aggiungere regole. Atteso: accesso consentito solo dalla subnet autorizzata, non da qualsiasi origine.

Se non hai ancora un firewall applicativo, almeno verifica che la porta non sia esposta pubblicamente con un test esterno controllato o con la configurazione del security group se sei in cloud.

Creare il primo core o collection

Solr può lavorare con core singoli o con collection, in base alla modalità che scegli. Per un’installazione base locale, un core è il modo più rapido per validare la piattaforma.

Se usi un core, crea la directory dati e la configurazione iniziale. La procedura varia in base alla versione, ma il concetto è sempre lo stesso: definire un nome core, un path dati e uno schema iniziale.

Un controllo utile è verificare la presenza delle configurazioni predefinite e la struttura nel path dati:

find /var/solr -maxdepth 2 -type d
find /opt/solr -maxdepth 2 -type f | head

Atteso: directory del core presente, senza errori di permesso. Se la directory non si crea, il problema è quasi sempre ownership o path errato nel comando di avvio.

Test di indicizzazione e query

Il modo più semplice per sapere se Solr funziona davvero è inviare un documento di test e poi interrogarlo. Non fermarti alla pagina web “up”: serve una prova di lettura e scrittura.

Con l’API HTTP puoi fare un test minimale. Adatta il nome del core se necessario.

curl -X POST -H 'Content-Type: application/json' \
  'http://127.0.0.1:8983/solr/testcore/update?commit=true' \
  --data-binary '[{"id":"1","title":"Test Solr Debian 12"}]'

curl 'http://127.0.0.1:8983/solr/testcore/select?q=id:1&wt=json'

Atteso: il primo comando restituisce una risposta senza errori HTTP; il secondo mostra il documento indicizzato. Se la query non trova nulla, controlla che il commit sia avvenuto e che il core si chiami davvero testcore.

Se l’API risponde con errore 404, il core non esiste o il path è sbagliato. Se risponde 500, guarda i log applicativi prima di cambiare configurazione.

Log, diagnostica e punti di controllo

Quando qualcosa non torna, i primi due posti da guardare sono journalctl e i log di Solr. A seconda della configurazione, i log possono stare in /var/log/solr o essere convogliati nel journal.

journalctl -u solr -n 200 --no-pager
ls -l /var/log/solr
find /var/solr -maxdepth 3 -type f | head

Artefatti utili da cercare:

• errori di startup Java.
• permessi negati su directory dati.
• porta occupata o bind fallito.
• eccezioni durante la creazione del core.

Se devi fare troubleshooting rapido, la sequenza pratica è: stato servizio, porta in ascolto, log, poi test HTTP locale. Cambiare configurazione senza questi quattro riscontri allunga solo il tempo di diagnosi.

Hardening minimo consigliato

Una volta che l’installazione funziona, chiudi le cose più ovvie. Solr non dovrebbe essere esposto liberamente se non c’è un motivo preciso.

• Limita l’accesso alla porta 8983 con firewall o reverse proxy.
• Se possibile, esponi Solr solo su 127.0.0.1 e pubblicalo dietro Apache o Nginx.
• Verifica i permessi di /var/solr e /var/log/solr.
• Non salvare credenziali in chiaro nei file di avvio.

Se la macchina è raggiungibile da reti non fidate, considera l’autenticazione e, se usi un proxy, TLS end-to-end o almeno TLS fino al proxy con rete interna controllata verso Solr.

Aggiornamento e rollback

Il vantaggio del tarball è che il rollback è semplice: tieni la versione precedente disponibile e conserva il path dei dati separato dai binari. Se un upgrade rompe l’avvio, puoi tornare alla release precedente senza toccare i dati.

Schema pratico:

1. ferma il servizio con systemctl stop solr;
2. salva la directory corrente dei binari;
3. installa la nuova versione in un path separato;
4. verifica l’avvio in locale;
5. riattiva il servizio solo dopo test HTTP e log puliti.

Rollback minimo: ripristina la directory binaria precedente e riavvia il servizio. I dati in /var/solr restano invariati, quindi il blast radius è limitato ai binari e alla configurazione del servizio.

Checklist finale operativa

Prima di considerare chiusa l’installazione, verifica questi punti:

• java -version mostra una JVM compatibile.
• systemctl status solr è active (running).
• ss -ltnp | grep 8983 mostra il listener corretto.
• curl -I http://127.0.0.1:8983/solr/ risponde senza errori.
• Un documento di test viene indicizzato e recuperato via query.

Se uno di questi controlli fallisce, non andare avanti con tuning o customizzazione: prima chiudi la base, poi lavori su schema, collection, sicurezza e performance.

Assunzione: i comandi e i path mostrati vanno adattati alla release esatta di Solr scaricata e alla modalità di gestione dei core scelta nel tuo ambiente.