Come installare FreshRSS su un VPS Ubuntu

Cosa stai configurando

Un lettore RSS self-hosted è un lettore di feed eseguito su un server di tua proprietà. Nessuno può quindi arrestarlo o modificare i contenuti che visualizza. Questa guida installa FreshRSS su un VPS Ubuntu 24.04: Apache come frontend, PHP come backend, MariaDB per l'archiviazione e un cron job che recupera i nuovi articoli. RSS (really simple syndication) è il formato di file che un sito pubblica affinché i software possano leggere i relativi articoli. FreshRSS è l'applicazione PHP che raccoglie questi file, conserva gli articoli e fornisce un'interfaccia web oltre a un'API (application programming interface) utilizzata dalle app per smartphone.

L'installazione è semplice: estrai una release, crea un database, scrivi un virtual host, esegui l'installer da riga di comando, quindi crea l'account con cli/create-user.php. La maggior parte del lavoro riportato di seguito riguarda gli aspetti che spesso vengono configurati in modo errato dopo l'installazione: il job di aggiornamento, le slash codificate per l'API mobile e la proprietà dei file.

FreshRSS 1.30.4, pubblicato il 21 ottobre 2026, è la release corrente al 29 ottobre 2026 e richiede PHP 8.1 o versioni successive. Ubuntu 24.04 include PHP 8.3, quindi sono sufficienti i pacchetti della distribuzione e non è necessario un repository PHP di terze parti.

Partire da uno stack LAMP funzionante

FreshRSS è una normale applicazione PHP e richiede la stessa base delle altre applicazioni. Se non hai ancora predisposto questa base, segui prima la procedura di configurazione dello stack LAMP per Ubuntu 24.04, quindi torna qui. In sintesi:

sudo apt update
sudo apt install -y apache2 mariadb-server php libapache2-mod-php
sudo systemctl enable --now apache2 mariadb

systemctl status apache2 dovrebbe restituire active (running). Se Apache non si avvia, la causa più comune è un altro processo che sta già utilizzando la porta 80; sudo ss -ltnp | grep :80 ne mostra il nome.

Le estensioni PHP necessarie a FreshRSS

FreshRSS considera obbligatorie libxml, cURL, JSON, PDO_MySQL, PCRE e ctype. Richiede inoltre mbstring, iconv, Zlib e ZipArchive, oltre a GMP sui sistemi a 32 bit. Su Ubuntu queste estensioni sono disponibili come pacchetti della distribuzione:

sudo apt install -y php-curl php-mbstring php-xml php-zip php-mysql php-intl php-gmp
sudo systemctl restart apache2

Verifica quali estensioni PHP sono state effettivamente caricate con php -m. Un'estensione mancante non impedisce l'avvio dell'installer. L'installazione si interrompe invece nella schermata dei requisiti, con una riga rossa che indica l'estensione mancante. Scoprire il problema solo in quel punto può creare confusione, quindi esegui subito la verifica. Riavviare Apache è importante perché libapache2-mod-php mantiene PHP all'interno del processo Apache. Un'estensione installata da poco non è quindi visibile al server web finché Apache non viene riavviato.

Scaricare la release

Installare FreshRSS al di fuori della web root predefinita e configurare Apache affinché la utilizzi. Mantenere la directory dell'applicazione separata dalla document root significa che tramite HTTP sarà raggiungibile soltanto la directory pubblica.

cd /tmp
curl -fsSLO https://github.com/FreshRSS/FreshRSS/archive/refs/tags/1.30.4.tar.gz
tar xzf 1.30.4.tar.gz
sudo mv FreshRSS-1.30.4 /srv/freshrss

Impostare ora i permessi, come richiesto dalla documentazione di FreshRSS: l'utente del server web deve essere il proprietario dell'albero delle directory, il gruppo deve poter leggere ogni file e deve poter scrivere in ./data/.

sudo chown -R www-data:www-data /srv/freshrss
sudo chmod -R g+r /srv/freshrss
sudo chmod -R g+w /srv/freshrss/data

Se si salta questo passaggio, l'installer non riesce a scrivere la configurazione perché PHP viene eseguito come www-data e www-data non può scrivere in una directory di proprietà di root.

Creare il database

FreshRSS supporta SQLite, MariaDB, MySQL e PostgreSQL. SQLite richiede l'estensione php-sqlite3, ma non richiede la configurazione di un server di database e memorizza i dati di ogni utente in un file data/users/_user_/db.sqlite separato. L'aggiunta di utenti non inserisce i relativi dati in un unico file SQLite condiviso; questa guida usa MariaDB come parte dello stack LAMP.

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

Usare utf8mb4 e non utf8. I feed contengono emoji e caratteri di alfabeti non latini, mentre la codifica utf8, a tre byte, non può memorizzare i caratteri a quattro byte. In modalità strict predefinita di MariaDB, i caratteri non supportati causano un errore; il troncamento dipende dalla modalità SQL e da opzioni dell'istruzione come IGNORE.

L’host virtuale Apache

La directory pubblica è p/, non la directory principale dell’albero. Tutto il resto, incluso il file di configurazione che contiene la password del database, si trova sopra la document root, dove Apache non lo servirà mai.

<VirtualHost *:80>
	ServerName rss.example.com
	DocumentRoot /srv/freshrss/p/

	<Directory /srv/freshrss/p>
		AllowOverride AuthConfig FileInfo Indexes Limit
		Require all granted
	</Directory>

	ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log
	CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined

	AllowEncodedSlashes On
</VirtualHost>

Salva il file come /etc/apache2/sites-available/freshrss.conf e abilitalo:

sudo a2enmod rewrite
sudo a2ensite freshrss
sudo a2dissite 000-default
sudo apache2ctl configtest
sudo systemctl reload apache2

configtest dovrebbe stampare Syntax OK. AllowEncodedSlashes On sembra facoltativo, ma non lo è: l’API di Google Reader invia identificatori dei feed che contengono %2F e, senza questa direttiva, Apache li rifiuta. Di conseguenza, le applicazioni mobili non riescono a sincronizzarsi, mentre l’interfaccia web continua a funzionare correttamente.

Aggiungi HTTPS prima di accedere

Stai per inserire una password in questo sito, quindi procurati prima un certificato. Punta un record A al server, quindi segui la procedura di configurazione di Certbot per Apache su Ubuntu ed esegui sudo certbot --apache -d rss.example.com. Certbot riscrive il virtual host per la porta 443 e aggiunge il redirect. Verifica con curl -I https://rss.example.com/, che dovrebbe restituire un 200 oppure un redirect alla pagina di accesso.

Esegui il programma di installazione dalla riga di comando

FreshRSS include un programma di installazione nel browser, ma la versione dalla riga di comando è ripetibile e conserva un record preciso delle opzioni selezionate.

sudo -u www-data php /srv/freshrss/cli/do-install.php \
  --default-user admin --auth-type form --environment production \
  --base-url https://rss.example.com --language en --api-enabled \
  --db-type mysql --db-host localhost --db-user freshrss \
  --db-password 'ReplaceThisPassword' --db-base freshrss
sudo -u www-data php /srv/freshrss/cli/create-user.php \
  --user admin --password 'a-long-passphrase' --api-password 'a-different-passphrase'

Esegui entrambi i comandi come www-data. Se li esegui come root, vengono creati file di configurazione di proprietà di root e l'interfaccia web non riesce più a salvare le impostazioni. Anche --environment production è importante, perché l'impostazione di sviluppo stampa le notifiche PHP nella pagina.

Carica https://rss.example.com/ e accedi con admin.

Perché i feed non si aggiornano automaticamente

Nessun processo interroga i feed finché non lo si configura. L'apertura di FreshRSS non pianifica il recupero dei feed; senza uno scheduler, usare il collegamento di aggiornamento nel menu di navigazione per recuperare manualmente gli articoli. La correzione consiste nello script fornito dal progetto a questo scopo, app/actualize_script.php, eseguito da cron.

sudo crontab -u www-data -e

Aggiungere una riga:

*/20 * * * * php /srv/freshrss/app/actualize_script.php > /tmp/FreshRSS.log 2>&1

Venti minuti sono una pianificazione ragionevole, ma continua ad applicarsi l'intervallo di aggiornamento di ciascun feed: il valore predefinito è un'ora e i singoli feed supportano intervalli fino a quindici minuti. Eseguirlo prima manualmente:

sudo -u www-data php /srv/freshrss/app/actualize_script.php

Un output corretto indica l'esecuzione dell'aggiornamento e termina senza errori PHP; i nomi dei feed vengono visualizzati quando gli articoli vengono aggiunti o aggiornati. Se non stampa assolutamente nulla, controllare l'output degli errori di PHP e i log di FreshRSS; il solo silenzio non identifica l'utente di cron come causa. Un errore di autorizzazione su data/ richiede di verificare il proprietario e i permessi di scrittura.

Aggiungi i primi feed

Usa il pulsante con il segno più in alto a sinistra dell’interfaccia, incolla l’indirizzo di un sito e FreshRSS individuerà automaticamente il link al feed. La maggior parte dei siti ne pubblica ancora uno anche quando non lo indica esplicitamente, in genere all’indirizzo /feed, /rss o /atom.xml. Le categorie sono cartelle e per spostare un feed da una categoria all’altra è sufficiente trascinarlo.

Se provieni da un altro reader, esporta da lì un file OPML e importalo nella pagina di gestione delle sottoscrizioni. OPML (outline processor markup language) è il formato standard per gli elenchi di feed e tutti i reader che vale la pena utilizzare supportano l’importazione e l’esportazione in questo formato. Un’importazione di grandi dimensioni è lenta al primo aggiornamento perché ogni feed viene recuperato una volta; attendi quindi il primo avvio di cron prima di valutarne la velocità.

Leggilo sul telefono

FreshRSS supporta l'API di Google Reader, compatibile con molte app RSS. Devono essere vere due condizioni. Nelle impostazioni di autenticazione, l'opzione "Allow API access" deve essere attiva; il flag --api-enabled riportato sopra l'ha già attivata. Nel profilo, il campo della password API deve contenere un valore. Questa password è separata intenzionalmente da quella di accesso, perché un telefono è più facile da perdere.

Apri https://rss.example.com/api/ per eseguire automaticamente i controlli della configurazione del server. Una configurazione funzionante restituisce PASS. Se il controllo non riesce, verifica l'impostazione AllowEncodedSlashes On dell'host virtuale e l'errore segnalato. Nell'app, inserisci https://rss.example.com/api/greader.php come indirizzo del server, il tuo utente FreshRSS come nome utente e la password API come password.

L’alternativa Docker

Se preferisci non gestire manualmente PHP e Apache, il progetto pubblica un’immagine ufficiale freshrss/freshrss e un file Compose ti fornisce l’applicazione insieme al relativo database. Il compromesso è quello consueto: meno componenti da gestire sull’host, ma un ulteriore livello da analizzare quando qualcosa non funziona. Per TLS (Transport Layer Security) serve comunque un reverse proxy. Se questa soluzione è più adatta alle tue esigenze, la guida di base a Docker Compose per un VPS illustra il formato del file e la riga di cron diventa docker exec --user www-data freshrss php ./app/actualize_script.php.

Backup e aggiornamenti

Due elementi contengono il tuo stato: il database e /srv/freshrss/data/. Esegui il dump del primo con sudo mysqldump freshrss > freshrss.sql, copia il secondo e conserva entrambi in un luogo diverso da questo server. Anche l’elenco delle sottoscrizioni merita un’esportazione OPML occasionale, perché questo file trasferisce l’elenco dei feed ad altri lettori che supportano OPML. Non conserva le impostazioni specifiche di FreshRSS, come frequenza di aggiornamento, credenziali, user agent o regole XPath per il web scraping; usa un’esportazione SQLite per conservare anche queste impostazioni.

L’aggiornamento consiste nell’estrarre una release più recente nella stessa directory e nell’eseguire nuovamente i comandi per la proprietà dei file. Segui il percorso di aggiornamento del progetto, release per release, e verifica FreshRSS dopo ogni passaggio. FreshRSS applica le proprie migrazioni del database al caricamento della pagina successivo. Esegui prima il backup, perché una migrazione non riuscita su un database che non puoi ripristinare lascia il sistema in uno stato irrecuperabile. Se hai eseguito l’installazione da un tarball precedente, ad esempio 1.29.1, passa a 1.30.4: le release di sicurezza 1.30.x includono la rotazione dell’ID di sessione quando cambiano i dati di autenticazione e limiti per le importazioni ZIP, mentre 1.30.4 aggiorna anche le immagini Docker Alpine alternative per risolvere gravi vulnerabilità di PHP. Un lettore di feed è un servizio a basso rischio da eseguire e un buon primo candidato se stai esaminando un elenco di ciò che vale la pena ospitare autonomamente.

FAQ

Perché i miei feed si aggiornano solo quando apro FreshRSS?

L'apertura della pagina non pianifica il recupero dei feed; senza uno scheduler, usa il link di aggiornamento per eseguire un refresh manuale. Aggiungi la riga cron che richiama app/actualize_script.php come utente www-data, quindi esegui manualmente lo script una volta e leggine l'output. Se non produce output, controlla l'output degli errori di PHP e i log di FreshRSS, quindi verifica che l'utente cron disponga dell'accesso in scrittura a data/.

La mia applicazione mobile non riesce a connettersi, ma il sito web funziona. Perché?

La Google Reader API inserisce slash codificati (%2F) nei percorsi delle richieste e Apache li rifiuta per impostazione predefinita. Aggiungi AllowEncodedSlashes On all'interno del virtual host e ricarica Apache. Conferma la correzione aprendo https://rss.example.com/api/, dove il controllo automatico della configurazione dovrebbe indicare PASS. Verifica anche che la password API sia impostata nel tuo profilo, perché è distinta dalla password di accesso.

Devo usare SQLite o MariaDB?

SQLite richiede l'estensione php-sqlite3, ma non richiede la gestione di un server di database né di una password del database. Ogni utente dispone di un file di database SQLite separato, quindi l'aggiunta di un secondo utente non crea contesa su un unico file condiviso e non richiede MariaDB. Usa MariaDB se vuoi utilizzare il server di database già presente nel tuo stack LAMP. In seguito è possibile passare dall'uno all'altro tramite i comandi di esportazione e importazione, quindi non si tratta di una scelta permanente.

L'installer non riesce a scrivere la configurazione. Qual è il problema?

PHP viene eseguito come www-data sotto Apache e questo utente non può scrivere in una directory di proprietà di root. Esegui nuovamente sudo chown -R www-data:www-data /srv/freshrss e sudo chmod -R g+w /srv/freshrss/data, quindi riavvia l'installer. Se hai già eseguito l'installer dalla riga di comando come root, correggi la proprietà dei file creati in data/ prima di riprovare.

Di quante risorse server ha bisogno un lettore RSS self-hosted?

Molto poche. FreshRSS è progettato per funzionare su hardware modesto, ma il consumo di risorse dipende dai feed, dalle dimensioni degli articoli e dalle impostazioni di conservazione. Lo spazio su disco aumenta con il periodo di conservazione, quindi imposta una politica di eliminazione degli articoli nelle impostazioni di archiviazione invece di conservarli tutti indefinitamente.