Installare FreshRSS su un VPS Ubuntu 24.04

Cosa stai configurando

Un lettore RSS self-hosted è un lettore di feed eseguito su un server di tua proprietà. Nessuno può 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 processo cron che recupera i nuovi articoli. RSS (really simple syndication) è il formato di file che un sito pubblica affinché il software possa 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 telefoni.

L'installazione è semplice: estrarre una release, creare un database, configurare un virtual host ed eseguire un installer dalla riga di comando. La maggior parte dei problemi si verifica nelle fasi successive, in particolare con il processo di aggiornamento, le slash codificate per l'API mobile e la proprietà dei file.

FreshRSS 1.29.1 è la release corrente a luglio 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 serve un repository PHP di terze parti.

Parti da uno stack LAMP funzionante

FreshRSS è una normale applicazione PHP, quindi richiede la stessa base di qualsiasi altra applicazione. Se non hai ancora configurato questa base, segui prima la configurazione dello stack LAMP per Ubuntu 24.04 e poi torna qui. In breve:

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.

Estensioni PHP richieste da FreshRSS

FreshRSS considera obbligatorie libxml, cURL, JSON, PDO_MySQL, PCRE e ctype. Richiede anche 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 del programma di installazione. Ne interrompe l'esecuzione nella schermata dei requisiti, con una riga rossa che indica l'estensione. Scoprire il problema in quel punto può creare confusione, quindi esegui subito la verifica. Il riavvio di Apache è importante perché libapache2-mod-php mantiene PHP all'interno del processo Apache. Di conseguenza, il server Web non vede una nuova estensione installata finché Apache non viene riavviato.

Scaricare la release

Installare FreshRSS al di fuori della document root predefinita e configurare Apache per indirizzarvisi. Mantenere separata la directory dell'applicazione dalla document root garantisce che tramite HTTP sia raggiungibile solo la directory pubblica.

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

Impostare ora i permessi, secondo i requisiti rigorosi della documentazione di FreshRSS: l'utente del server Web è proprietario dell'albero, il gruppo può leggere ogni file e può 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 propria 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 non richiede configurazione ed è adatto a una sola persona con alcune centinaia di feed. MariaDB è la scelta migliore quando più persone condividono l'istanza, perché le scritture simultanee del processo di aggiornamento e dell'interfaccia web non competono più per un singolo lock sul file.

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 possono contenere emoji e alfabeti non latini, mentre la precedente codifica a tre byte utf8 tronca il titolo di un articolo al primo carattere a quattro byte.

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 contenenti %2F e, senza questa direttiva, Apache li rifiuta. Di conseguenza, le applicazioni mobili non riescono a sincronizzarsi mentre l'interfaccia web funziona correttamente.

Aggiungi HTTPS prima di accedere

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

Eseguire il programma di installazione dalla riga di comando

FreshRSS include un programma di installazione nel browser, ma la versione da riga di comando è ripetibile e conserva un registro esatto delle opzioni scelte.

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'

Eseguire entrambi i comandi come www-data. Se vengono eseguiti 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.

Caricare https://rss.example.com/ e accedere come admin.

Perché i feed non si aggiornano automaticamente

Nessun processo interroga i feed finché non lo configuri. FreshRSS si aggiorna mentre un browser è aperto sulla relativa interfaccia. Di conseguenza, un'istanza che visiti due volte al giorno mostra articoli vecchi di dodici ore. La soluzione è lo script fornito dal progetto per questo scopo, app/actualize_script.php, eseguito da cron.

sudo crontab -u www-data -e

Aggiungi una riga:

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

Venti minuti sono l'intervallo minimo consigliato, perché lo script non aggiorna lo stesso feed più spesso di una volta ogni venti minuti. Un intervallo più breve usa solo CPU inutilmente. Eseguilo prima manualmente:

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

Un output normale indica ogni feed recuperato e termina senza errori PHP. Se non stampa nulla, l'utente di cron è errato. Un errore di autorizzazione su data/ indica che il passaggio chmod -R g+w è stato saltato.

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 del feed. La maggior parte dei siti continua a pubblicarne uno anche quando non lo segnala, in genere in /feed, /rss o /atom.xml. Le categorie sono cartelle e per spostare un feed tra di esse basta trascinarlo.

Se provieni da un altro lettore, esporta un file OPML da quel lettore e importalo nella pagina di gestione delle sottoscrizioni. OPML (outline processor markup language) è il formato standard per gli elenchi di feed e tutti i lettori che vale la pena usare supportano l’importazione. Un’importazione di grandi dimensioni è lenta al primo aggiornamento perché ogni feed viene recuperato una volta; attendi che la prima esecuzione di cron termini prima di valutare la velocità.

Leggilo sul telefono

FreshRSS implementa l'API di Google Reader, supportata dalla maggior parte delle 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à impostata. Nel profilo, il campo della password API deve contenere un valore. Questa password è volutamente separata da quella di accesso, perché un telefono è più facile da perdere.

Visita https://rss.example.com/api/ e seleziona "Check full server configuration". Una configurazione funzionante restituisce PASS. In caso di errore, quasi sempre manca la riga AllowEncodedSlashes On. Nell'app, specifica l'indirizzo del server come https://rss.example.com/api/greader.php, il nome utente come il tuo utente FreshRSS 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 unico file Compose ti fornisce l'applicazione e il relativo database. Il compromesso è quello consueto: meno componenti da gestire sull'host, un ulteriore livello da sottoporre a debug quando qualcosa non funziona e la necessità di un reverse proxy per TLS (Transport Layer Security). Se questa soluzione è più adatta alle tue esigenze, le nozioni di base di Docker Compose per un VPS illustrano 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 conservano 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. Vale anche la pena esportare occasionalmente l'elenco degli abbonamenti in formato OPML, perché questo file ricrea la configurazione di lettura con qualsiasi software RSS.

Per eseguire l'aggiornamento, estrai una release più recente nella stessa directory e ripeti i comandi per la proprietà. FreshRSS applica le proprie migrazioni del database al caricamento della pagina successiva. Esegui prima un backup, perché una migrazione non riuscita su un database che non puoi ripristinare crea una situazione irrecuperabile. Un lettore RSS è un servizio a basso rischio da eseguire ed è un buon primo candidato se stai valutando un elenco di servizi che vale la pena ospitare autonomamente.

FAQ

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

Perché non esiste alcuna pianificazione finché non ne crei una. FreshRSS aggiorna i feed mentre è aperta una sessione del browser e non esegue alcuna operazione quando la scheda è chiusa. 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. In genere, l'assenza di output indica che cron lo sta eseguendo con l'utente errato, quindi PHP non può scrivere in data/.

La mia app mobile non riesce a connettersi, ma il sito 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. Verifica la correzione aprendo https://rss.example.com/api/ ed eseguendo "Check full server configuration", che dovrebbe segnalare PASS. Controlla anche che la password API sia impostata nel tuo profilo, perché è separata dalla password di accesso.

Devo usare SQLite o MariaDB?

SQLite per un singolo utente, perché non è necessario installare nulla né gestire una password. MariaDB quando più di una persona legge sull'istanza oppure quando superi alcune centinaia di feed, perché il processo di aggiornamento e l'interfaccia web scrivono contemporaneamente e il blocco su un singolo file diventa il limite. In seguito puoi passare dall'uno all'altro tramite i comandi di esportazione e importazione, quindi non è una scelta definitiva.

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

PHP viene eseguito come www-data in 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, elimina i file che ha creato in data/ prima di riprovare, perché il problema effettivo è il proprietario dei file.

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

Di pochissime. Alcune centinaia di feed su un piano di piccole dimensioni non creano problemi, perché il carico consiste in brevi raffiche di richieste HTTP ogni venti minuti e il database rimane piccolo quando gli articoli meno recenti vengono eliminati. L'uso del disco cresce in base al periodo di conservazione, quindi imposta una politica di eliminazione degli articoli nelle impostazioni di archiviazione invece di conservarli per sempre.