Ospitare FreshRSS su un VPS gestito: i vostri feed RSS sul vostro server

Che cosa fa FreshRSS

FreshRSS è un aggregatore di feed RSS self-hosted scritto in PHP. Il suo README lo descrive come leggero, facile da usare, potente e personalizzabile, tradotto in più di venti lingue. È un'applicazione multiutente, con una modalità di lettura anonima ed etichette personalizzate.

• La lettura: i vostri abbonamenti ordinati in categorie, etichette, preferiti e ricerche salvate.
• WebSub: FreshRSS riceve all'istante i nuovi articoli dalle fonti compatibili, che li inviano senza attendere il prossimo aggiornamento.
• L'estrazione dalle pagine web: per un sito senza feed RSS o Atom, FreshRSS legge la pagina stessa con regole XPath, e sa leggere anche documenti JSON.
• La condivisione: una selezione di articoli può essere ripubblicata in HTML, RSS o OPML.
• Le app: un'API per le app mobili e desktop, un'interfaccia a riga di comando ed estensioni.

FreshRSS è sviluppato dalla sua comunità su GitHub, e il suo sito ufficiale è pubblicato dalla comunità FreshRSS. Le estensioni vivono in un repository separato, e la documentazione si rivolge a utenti, amministratori e sviluppatori.

Che cosa consente la licenza AGPL-3.0

FreshRSS è pubblicato con la GNU Affero General Public License, versione 3: il suo manifesto composer.json la dichiara come AGPL-3.0, e il suo README rimanda al testo della licenza. Quel testo afferma un'autorizzazione illimitata a eseguire il programma non modificato. Potete quindi usare l'immagine pubblicata dal progetto per la vostra azienda e il vostro team, senza alcuna licenza da acquistare.

L'articolo 13 aggiunge una condizione propria dell'AGPL: se modificate il programma, la vostra versione deve offrire a tutti coloro che la usano a distanza, tramite la rete, il modo di ottenerne gratuitamente il codice sorgente. Un'estensione di terzi aggiunta al volume extensions segue la propria licenza.

L'installazione con Docker Compose

Il progetto pubblica le sue immagini ufficiali su Docker Hub, come freshrss/freshrss, insieme a un file Compose di esempio. Su un server in cui Docker è installato, create una cartella chiamata freshrss e collocatevi questo compose.yaml, tratto da quel file e dal README Docker:

volumes:
  data:
  extensions:

services:
  freshrss:
    image: freshrss/freshrss:latest
    container_name: freshrss
    hostname: freshrss
    restart: unless-stopped
    logging:
      options:
        max-size: 10m
    volumes:
      - data:/var/www/FreshRSS/data
      - extensions:/var/www/FreshRSS/extensions
    ports:
      - 127.0.0.1:8080:80
    environment:
      TZ: UTC
      CRON_MIN: '3,33'
      TRUSTED_PROXY: 172.16.0.1/12 192.168.0.1/16
    healthcheck:
      test: ["CMD", "cli/health.php"]
      timeout: 10s
      start_period: 60s
      start_interval: 11s
      interval: 75s
      retries: 3

docker compose up -d

• Una porta pubblicata su 127.0.0.1: FreshRSS si raggiunge solo tramite il reverse proxy, installato sullo stesso server. Il file di esempio del progetto pubblica la porta 8080 per un uso locale; qui l'indirizzo 127.0.0.1 la riserva al proxy.
• Il volume data contiene la configurazione, gli account e, con SQLite, il database di ogni utente. Il README ricorda che contiene tutti i dati personali. Docker Compose lo chiama con il nome della cartella: freshrss_data.
• Il volume extensions contiene le estensioni di terzi, se ne aggiungete.
• TZ prende il fuso orario del server, nel formato PHP; per impostazione predefinita vale UTC.
• TRUSTED_PROXY mantiene il valore del file di esempio: le reti private da cui provengono le richieste del proxy. Decide quale indirizzo finisce nei log, quello del visitatore o quello del proxy.
• Il controllo di salute esegue cli/health.php a intervalli regolari, perché Docker sappia se l'istanza risponde.

Il tag latest, quello predefinito, segue l'ultima versione numerata; edge segue la versione continua; un tag come 1.30.4 fissa una versione, e il suffisso -alpine dà lo stesso risultato su una base Alpine anziché Debian. La sezione sugli aggiornamenti torna su questa scelta.

Completare l'installazione

Una volta al suo posto il reverse proxy, aprite il vostro indirizzo HTTPS: la procedura guidata chiede la lingua, verifica il server, propone la scelta del database, poi crea l'account amministratore, con la sua password e il metodo di accesso. SQLite funziona senza nulla da preparare. L'installazione si fa anche da riga di comando, con cli/do-install.php e cli/create-user.php, lanciati tramite docker exec --user www-data freshrss.

Quanto alle risorse, il README chiede un server leggero, con Linux o Windows, e segnala che FreshRSS gira perfino su un Raspberry Pi 1, con tempi di risposta inferiori al secondo, con 150 feed e 22.000 articoli. La taglia dipende dal numero di utenti, di feed e di articoli conservati. Su un VPS gestito, descrivetici il vostro uso e vi raccomandiamo la taglia adatta.

HTTPS: il reverse proxy

In produzione, il README Docker consiglia un reverse proxy sul server host, che fornisce HTTPS. Scegliete prima un nome di dominio o un sottodominio, come rss.example.com, che punta al server con record A e AAAA. Il progetto raccomanda Traefik e pubblica per esso un file Compose completo, con i certificati Let's Encrypt e il reindirizzamento da HTTP a HTTPS; fornisce anche esempi per Apache, Nginx e Caddy.

Con Caddy

Caddy ottiene il certificato e attiva HTTPS da solo. Questo blocco segue l'esempio della documentazione per un sottodominio, puntato qui sulla porta pubblicata in locale:

rss.example.com {
  reverse_proxy 127.0.0.1:8080
}

Con Nginx e Certbot

Questo blocco segue l'esempio Nginx del README Docker per la radice di un dominio, ridotto alla porta 80 per lasciare a Certbot l'attivazione di HTTPS. Le ultime due righe trasmettono l'intestazione Authorization, necessaria all'API Google Reader:

upstream freshrss {
  server 127.0.0.1:8080;
  keepalive 64;
}

server {
  listen 80;
  listen [::]:80;
  server_name rss.example.com;

  location / {
    proxy_pass http://freshrss/;
    proxy_redirect off;
    proxy_buffering off;
    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 $scheme;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_read_timeout 90;

    proxy_set_header Authorization $http_authorization;
    proxy_pass_header Authorization;
  }
}

Certbot installa poi il certificato e si occupa di rinnovarlo:

sudo certbot --nginx

L'indirizzo pubblico: base_url

FreshRSS conserva il proprio indirizzo pubblico in base_url, nel file data/config.php. L'API e WebSub si basano su di esso: verificate che contenga il vostro indirizzo https. Il README Docker indica dove trovare questo file nel volume:

docker volume inspect freshrss_data
sudo nano /var/lib/docker/volumes/freshrss_data/_data/config.php
docker compose restart freshrss

'base_url' => 'https://rss.example.com/',

L'aggiornamento dei feed: CRON_MIN

FreshRSS recupera i nuovi articoli con il suo script app/actualize_script.php. L'immagine Docker include un'attività pianificata che lo esegue ai minuti indicati in CRON_MIN. Senza questa variabile, o con un valore vuoto, l'attività resta disattivata e i feed non si aggiornano più da soli.

• Il ritmo: il progetto raccomanda circa due esecuzioni all'ora, per esempio 13,43; funziona anche */20.
• Il limite: lo script non aggiorna lo stesso feed più di una volta ogni venti minuti, quindi una cadenza più fitta non porta nulla.
• Il tempo reale: WebSub subentra per le fonti compatibili. Richiede un indirizzo pubblico, letto da base_url, e la procedura guidata lo attiva quando il server ne ha uno.

Un altro metodo documentato: un'attività pianificata sul server host, che chiama lo script all'interno del container. In questo caso, togliete CRON_MIN da compose.yaml, per mantenere un solo metodo:

7,37 * * * * root docker exec --user www-data freshrss php ./app/actualize_script.php > /tmp/FreshRSS.log 2>&1

Dalla versione 1.30.0, FreshRSS rifiuta per impostazione predefinita gli indirizzi della rete locale come 127.0.0.1, per proteggersi dalla falsificazione delle richieste lato server. Un servizio vicino che produce feed, come RSS-Bridge, si autorizza tramite la variabile INTERNAL_HOST_ALLOWLIST, nella forma rss-bridge:80, oppure nella configurazione di sistema. Il valore * toglie ogni controllo, e la documentazione lo giudica non sicuro.

Gli account e l'accesso

Durante l'installazione, FreshRSS propone l'accesso tramite modulo, che richiede JavaScript. È il metodo predefinito, e si adatta alla maggior parte delle istanze. La documentazione ne descrive altri:

La documentazione avverte che FreshRSS si fida di qualsiasi indirizzo elencato in TRUSTED_PROXY: un proxy mal protetto permetterebbe a un malintenzionato di impostare l'intestazione e di ottenere l'accesso da amministratore. Qui la porta ascolta solo su 127.0.0.1, il che la riserva al proxy del server stesso. La documentazione sconsiglia inoltre qualsiasi istanza senza autenticazione non appena il server è raggiungibile dall'esterno della vostra rete.

Le registrazioni e gli utenti

• Chiuse per impostazione predefinita: la configurazione fissa il numero di account a 1, quello dell'amministratore. Il modulo di registrazione compare solo se aumentate questo numero, in Amministrazione, Configurazione di sistema; 0 toglie ogni limite.
• Gli account creati dall'amministratore: Amministrazione, Gestione utenti, con la lingua, il nome utente, la password e l'eventuale ruolo di amministratore.
• Una nuova autenticazione è richiesta prima delle azioni sensibili, come promuovere un utente o applicare un aggiornamento, dopo 20 minuti per impostazione predefinita.
• La convalida dell'indirizzo e-mail è facoltativa. Richiede un server SMTP, impostato con mailer e smtp in data/config.php: la documentazione indica che l'invio tramite la funzione mail di PHP non è ancora supportato nelle immagini Docker ufficiali.

Per un'istanza condivisa da più persone, la documentazione consiglia di aprire gli account a persone di fiducia e di tenere l'istanza dietro un proxy o un firewall che blocchi l'accesso alle reti di indirizzi interni.

Le app mobili: le API Google Reader e Fever

FreshRSS funziona nel browser, su schermi grandi come su quelli piccoli, e in app per Android, iOS, Linux, Windows e macOS. Queste app usano una delle sue due API: Google Reader, che il README giudica la migliore, e Fever, con funzioni più limitate, meno efficiente e meno sicura.

1. Come amministratore, nella sezione Autenticazione, attivate l'opzione che consente l'accesso tramite API.
2. Ogni utente sceglie una password API nel proprio profilo. È distinta dalla password principale, dà accesso a meno cose ed è pensata per le situazioni meno sicure.
3. Nell'app, inserite l'indirizzo https://rss.example.com/api/greader.php, oppure https://rss.example.com/api/fever.php per Fever, con il nome utente e quella password API.

Per verificare, il link mostrato accanto alla password API, nel profilo, apre una pagina di prova: PASS sul controllo completo conferma che tutto funziona. L'immagine Docker imposta già Apache per accettare le barre codificate, che alcune app richiedono; con Nginx davanti, mantenete l'inoltro dell'intestazione Authorization.

Il README tiene una tabella delle app compatibili, con la loro piattaforma, la loro API e le loro funzioni: Capy Reader e Readrops su Android, FeedFlow su mobile e desktop, RSS Guard e NewsFlash su desktop, ReadKit e Reeder Classic su iOS e macOS, tra le altre.

SQLite, PostgreSQL, MySQL o MariaDB

FreshRSS integra SQLite, che il README Docker descrive come l'opzione più semplice, con buone prestazioni. La pagina dei requisiti raccomanda PostgreSQL 10 o successivo, e accetta anche MariaDB 10.6 e MySQL 8.0 o successivi. La scelta si fa nella procedura guidata di installazione.

Per PostgreSQL, aggiungete questo servizio a compose.yaml, tratto dal file docker-compose-db.yml del progetto, e il volume db all'elenco dei volumi. La password va in un file .env, accanto a compose.yaml:

  freshrss-db:
    image: postgres:18
    container_name: freshrss-db
    hostname: freshrss-db
    restart: unless-stopped
    logging:
      options:
        max-size: 10m
    volumes:
      - db:/var/lib/postgresql
    environment:
      POSTGRES_DB: freshrss
      POSTGRES_USER: freshrss
      POSTGRES_PASSWORD: ${DB_PASSWORD}

DB_PASSWORD='a-long-unique-password'

Nella procedura guidata, scegliete PostgreSQL e indicate freshrss-db come host, con l'utente, la password e il database freshrss.

Potete tornare su questa scelta in seguito. La documentazione descrive il passaggio da un database all'altro, da MySQL a PostgreSQL per esempio, o verso una versione principale più recente di PostgreSQL: cli/db-backup.php copia il database di ogni utente in un file SQLite, poi cli/db-restore.php lo carica nel nuovo database.

I backup

Il README precisa che FreshRSS è fornito senza alcuna garanzia: sono i vostri backup a custodire i vostri abbonamenti, i vostri articoli e le vostre impostazioni. Ecco che cosa la documentazione chiede di salvare:

I volumi, a servizio fermo

La documentazione ritiene più sicuro fermare il servizio durante le operazioni di manutenzione. I volumi Docker si copiano con un container temporaneo, il metodo descritto nella documentazione di Docker:

docker compose stop freshrss
docker run --rm --volumes-from freshrss -v "$PWD":/backup ubuntu tar -czf /backup/freshrss-$(date +%F).tgz --exclude=data/cache -C /var/www/FreshRSS data extensions
docker compose start freshrss

I database, a servizio attivo

Dalla versione 1.29.1, FreshRSS sa esportare da solo il database di ogni utente in un file SQLite, qualunque sia il database che usate, e conservare solo i più recenti. Attivate questa esportazione in data/config.php:

'auto_sqlite_export' => [
    'enabled' => true,
    'retention' => 7,
],

Pianificate poi il comando sul server, qui ogni notte. Ogni esecuzione scrive data/users/<user>/sqlite-backups/<date>.sqlite ed elimina i file oltre gli ultimi sette:

20 2 * * * root docker exec --user www-data freshrss cli/export-sqlite-auto.php --quiet

Con PostgreSQL, aggiungete un'esportazione con lo strumento del database stesso, come nel README Docker. L'opzione -T toglie il terminale, che a un'attività pianificata non serve:

docker compose exec -T freshrss-db pg_dump -U freshrss freshrss | gzip -9 > freshrss-postgres-$(date +%F).sql.gz

L'esportazione OPML, dall'interfaccia, salva l'elenco dei vostri feed, senza alcune impostazioni proprie di FreshRSS come le credenziali o le regole di estrazione delle pagine. Per una copia completa, conservate le esportazioni SQLite: collocate sul disco del server, rientrano anche nei suoi backup notturni.

Ripristinare

1. Fermate FreshRSS con docker compose stop freshrss.
2. Ricaricate l'archivio nei volumi: docker run --rm --volumes-from freshrss -v "$PWD":/backup ubuntu tar -xzf /backup/freshrss-YYYY-MM-DD.tgz -C /var/www/FreshRSS.
3. Con un database esterno, ripristinatelo dalla sua esportazione, oppure dai file SQLite con cli/db-restore.php --delete-backup --force-overwrite.
4. Rilanciate con docker compose start freshrss, poi verificate che i vostri feed e i vostri articoli ci siano.

Ripetete questo esercizio di tanto in tanto, su una copia: è così che verificate che un backup funzioni.

Gli aggiornamenti

Il README Docker fornisce due comandi, dalla cartella del compose.yaml. I volumi restano al loro posto:

docker compose pull
docker compose up -d

FreshRSS pubblica su due canali. Le versioni numerate, tag latest, escono qualche volta all'anno, senza un calendario fisso, e le loro correzioni non vengono riportate sulle versioni precedenti. La versione continua, tag edge, riceve le novità e le correzioni man mano che arrivano: dalla versione 1.30.0, il progetto la raccomanda per avere più rapidamente le correzioni di sicurezza.

• Prima il backup: la documentazione chiede un backup di data/, delle estensioni e del database prima di ogni aggiornamento.
• Versione per versione: se siete indietro di diverse versioni, passate da ciascuna, per esempio dalla 1.26.0 alla 1.27.1 prima della 1.28.1, verificando a ogni tappa. Con Docker, tag come 1.29.1 rendono possibile questo percorso.
• Le versioni recenti: la 1.30.4 del 21 ottobre 2026 è la quarta versione di sicurezza della serie 1.30. Corregge vulnerabilità di PHP nelle immagini Alpine, dopo la 1.30.3, che ha portato l'immagine Debian predefinita a Debian 13.

Per seguire le nuove versioni, il progetto pubblica un feed Atom delle sue versioni: abbonatevi con la vostra stessa istanza FreshRSS.

Chi fa che cosa su un VPS gestito

Il self-hosting richiede di occuparsi del server oltre che dell'applicazione. Su un VPS gestito, i nostri team prendono in carico il server e seguono la vostra istanza in modo proattivo; FreshRSS resta il vostro software, con le sue impostazioni e i suoi dati.

Se preferite che i nostri team intervengano nell'applicazione stessa, questa prestazione si fattura a ore o a forfait, con un preventivo comunicato prima dell'intervento.