Héberger FreshRSS sur un VPS géré : vos flux RSS sur votre serveur

Ce que fait FreshRSS

FreshRSS est un agrégateur de flux RSS auto-hébergé, écrit en PHP. Son README le décrit comme léger, simple à prendre en main, puissant et personnalisable, traduit dans plus de vingt langues. C'est une application multi-utilisateur, avec un mode de lecture anonyme et des étiquettes personnalisées.

• La lecture : vos abonnements rangés par catégories, des étiquettes, des favoris et des recherches enregistrées.
• WebSub : FreshRSS reçoit instantanément les nouveaux articles des sources compatibles, qui les poussent au lieu d'attendre l'actualisation suivante.
• L'extraction de pages : pour un site sans flux RSS ni Atom, FreshRSS lit la page elle-même avec des règles XPath, et sait aussi lire des documents JSON.
• Le partage : une sélection d'articles se republie en HTML, en RSS ou en OPML.
• Les applications : une API pour les applications mobiles et de bureau, une interface en ligne de commande et des extensions.

FreshRSS se développe en communauté sur GitHub, et son site officiel est publié par la communauté FreshRSS. Les extensions vivent dans un dépôt à part, et la documentation couvre les utilisateurs, les administrateurs et les développeurs.

Ce que permet la licence AGPL-3.0

FreshRSS est publié sous GNU Affero General Public License, version 3 : son manifeste composer.json le déclare AGPL-3.0, et son README renvoie au texte de la licence. Ce texte affirme une permission illimitée de faire tourner le programme non modifié. Vous pouvez donc utiliser l'image publiée par le projet pour votre entreprise et votre équipe, sans licence à acheter.

L'article 13 ajoute une condition propre à l'AGPL : si vous modifiez le programme, votre version doit offrir à tous ceux qui l'utilisent à distance, par le réseau, le moyen d'obtenir gratuitement son code source. Une extension tierce ajoutée dans le volume extensions suit sa propre licence.

L'installation avec Docker Compose

Le projet publie ses images officielles sur Docker Hub, sous freshrss/freshrss, et un fichier Compose d'exemple. Sur un serveur où Docker est installé, créez un dossier nommé freshrss et placez-y ce compose.yaml, tiré de ce fichier et du 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

• Un port publié sur 127.0.0.1 : FreshRSS s'atteint par le seul mandataire inverse, posé sur le même serveur. Le fichier d'exemple du projet publie le port 8080 pour un usage local ; l'adresse 127.0.0.1 le réserve ici au mandataire.
• Le volume data garde la configuration, les comptes et, avec SQLite, les bases de chaque utilisateur. Le README rappelle qu'il contient toutes les données personnelles. Docker Compose le nomme d'après le dossier : freshrss_data.
• Le volume extensions accueille les extensions tierces, si vous en ajoutez.
• TZ prend le fuseau horaire du serveur, au format de PHP ; il vaut UTC par défaut.
• TRUSTED_PROXY reprend la valeur du fichier d'exemple : les plages privées d'où arrivent les requêtes du mandataire. Elle décide de l'adresse inscrite aux journaux, celle du visiteur ou celle du mandataire.
• Le contrôle de santé lance cli/health.php à intervalle régulier : Docker sait ainsi si l'instance répond.

L'étiquette latest, celle par défaut, suit la dernière version publiée ; edge suit la version continue ; une étiquette comme 1.30.4 fixe une version, et le suffixe -alpine donne la même chose sur une base Alpine plutôt que Debian. La section des mises à jour revient sur ce choix.

Terminer l'installation

Une fois le mandataire inverse en place, ouvrez votre adresse HTTPS : l'assistant d'installation demande la langue, vérifie le serveur, propose la base de données, puis crée le compte administrateur, avec son mot de passe et la méthode de connexion. SQLite convient sans rien préparer. L'installation se fait aussi en ligne de commande, avec cli/do-install.php et cli/create-user.php, lancés par docker exec --user www-data freshrss.

Côté ressources, le README demande un serveur léger, sous Linux ou Windows, et précise que FreshRSS tourne même sur un Raspberry Pi 1, en moins d'une seconde par réponse, avec 150 flux et 22 000 articles. La taille dépend du nombre d'utilisateurs, de flux et d'articles gardés. Sur un VPS géré, décrivez-nous votre usage et nous vous recommandons la taille qui convient.

HTTPS : le mandataire inverse

Pour la production, le README Docker conseille un mandataire inverse sur le serveur hôte, qui fournit HTTPS. Choisissez d'abord un nom de domaine ou un sous-domaine, par exemple rss.example.com, qui pointe vers le serveur avec des enregistrements A et AAAA. Le projet recommande Traefik et publie un fichier Compose complet pour lui, avec les certificats Let's Encrypt et la redirection de HTTP vers HTTPS ; il donne aussi des exemples pour Apache, Nginx et Caddy.

Avec Caddy

Caddy obtient le certificat et active HTTPS de lui-même. Ce bloc reprend l'exemple de la documentation pour un sous-domaine, pointé ici vers le port publié en local :

rss.example.com {
  reverse_proxy 127.0.0.1:8080
}

Avec Nginx et Certbot

Ce bloc reprend l'exemple Nginx du README Docker pour la racine d'un domaine, réduit au port 80 pour laisser Certbot installer HTTPS. Les deux dernières lignes transmettent l'en-tête Authorization, dont l'API Google Reader a besoin :

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 installe ensuite le certificat et se charge de le renouveler :

sudo certbot --nginx

L'adresse publique : base_url

FreshRSS garde son adresse publique dans base_url, au fichier data/config.php. L'API et WebSub s'en servent : vérifiez qu'elle porte bien votre adresse en https. Le README Docker indique où trouver ce fichier dans le 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'actualisation des flux : CRON_MIN

FreshRSS récupère les nouveaux articles par son script app/actualize_script.php. L'image Docker embarque une tâche planifiée qui le lance aux minutes données par CRON_MIN. Sans cette variable, ou avec une valeur vide, la tâche reste éteinte et les flux ne s'actualisent plus d'eux-mêmes.

• Le rythme : le projet recommande environ deux passages par heure, par exemple 13,43 ; */20 fonctionne aussi.
• La limite : le script n'actualise pas un même flux plus d'une fois toutes les vingt minutes, et un rythme plus serré n'apporte donc rien.
• Le temps réel : WebSub prend le relais pour les sources compatibles. Il demande une adresse publique, lue dans base_url, et l'assistant d'installation l'active quand le serveur en a une.

Autre méthode documentée : une tâche planifiée sur le serveur hôte, qui appelle le script dans le conteneur. Retirez alors CRON_MIN du compose.yaml, pour ne garder qu'une seule méthode :

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

Depuis la version 1.30.0, FreshRSS refuse par défaut les adresses du réseau local, comme 127.0.0.1, pour se protéger des requêtes forgées côté serveur. Un service voisin qui produit des flux, comme RSS-Bridge, s'autorise par la variable INTERNAL_HOST_ALLOWLIST, sous la forme rss-bridge:80, ou dans la configuration système. La valeur * retire tout contrôle, et la documentation la juge dangereuse.

Les comptes et la connexion

À l'installation, FreshRSS propose la connexion par formulaire, qui demande JavaScript. C'est la méthode par défaut, et elle convient à la plupart des instances. La documentation en décrit d'autres :

La documentation prévient que FreshRSS fait confiance à toute adresse listée dans TRUSTED_PROXY : un mandataire mal protégé laisserait un attaquant définir l'en-tête et obtenir un accès administrateur. Ici, le port n'écoute que sur 127.0.0.1, ce qui le réserve au mandataire du serveur. Elle déconseille aussi toute instance sans authentification dès que le serveur s'atteint hors de votre réseau.

Les inscriptions et les utilisateurs

• Fermées par défaut : la configuration fixe à 1 le nombre de comptes, celui de l'administrateur. Le formulaire d'inscription n'apparaît que si vous relevez ce nombre, dans Administration, Configuration système ; 0 retire toute limite.
• Les comptes créés par l'administrateur : Administration, Gestion des utilisateurs, avec la langue, l'identifiant, le mot de passe et le rôle d'administrateur ou non.
• Une nouvelle authentification est demandée avant les actions sensibles, comme promouvoir un utilisateur ou appliquer une mise à jour, au-delà de 20 minutes par défaut.
• La vérification des adresses e-mail est facultative. Elle demande un serveur SMTP, réglé par mailer et smtp dans data/config.php : la documentation indique que l'envoi par la fonction mail de PHP ne fonctionne pas encore dans les images Docker officielles.

Pour une instance partagée entre plusieurs personnes, la documentation conseille d'ouvrir les comptes aux personnes de confiance et de garder l'instance derrière un mandataire ou un pare-feu qui bloque l'accès aux plages d'adresses internes.

Les applications mobiles : API Google Reader et Fever

FreshRSS se lit dans le navigateur, sur grand comme sur petit écran, et dans des applications pour Android, iOS, Linux, Windows et macOS. Elles passent par l'une de ses deux API : Google Reader, que le README juge la meilleure, et Fever, aux fonctions plus limitées, moins efficace et moins sûre.

1. En administrateur, dans la section Authentification, activez l'option qui autorise l'accès par l'API.
2. Chaque utilisateur choisit un mot de passe d'API dans son profil. Il est distinct du mot de passe principal, ouvre moins de choses, et sert dans des situations moins sûres.
3. Dans l'application, indiquez l'adresse https://rss.example.com/api/greader.php, ou https://rss.example.com/api/fever.php pour Fever, avec l'identifiant et ce mot de passe d'API.

Pour vérifier, le lien affiché à côté du mot de passe d'API, dans le profil, ouvre une page de test : PASS au contrôle complet confirme que tout fonctionne. L'image Docker règle déjà Apache pour accepter les barres obliques encodées, dont certaines applications ont besoin ; avec Nginx devant, gardez la transmission de l'en-tête Authorization.

Le README tient un tableau des applications compatibles, avec leur plateforme, leur API et leurs fonctions : Capy Reader et Readrops sur Android, FeedFlow sur mobile comme sur ordinateur, RSS Guard et NewsFlash sur ordinateur, ReadKit et Reeder Classic sur iOS et macOS, parmi d'autres.

SQLite, PostgreSQL, MySQL ou MariaDB

FreshRSS embarque SQLite, que le README Docker décrit comme la solution la plus simple, avec de bonnes performances. La page des prérequis recommande PostgreSQL 10 ou plus récent, et accepte aussi MariaDB 10.6 et MySQL 8.0 ou plus récents. Le choix se fait dans l'assistant d'installation.

Pour PostgreSQL, ajoutez ce service à compose.yaml, tiré du fichier docker-compose-db.yml du projet, et le volume db à la liste des volumes. Le mot de passe se place dans un fichier .env, à côté de 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='un-mot-de-passe-long-et-unique'

Dans l'assistant, choisissez PostgreSQL et indiquez freshrss-db comme hôte, avec l'utilisateur, le mot de passe et la base freshrss.

Ce choix se reprend plus tard. La documentation décrit le passage d'une base à l'autre, de MySQL à PostgreSQL par exemple, ou vers une version majeure plus récente de PostgreSQL : cli/db-backup.php copie la base de chaque utilisateur dans un fichier SQLite, puis cli/db-restore.php la recharge dans la nouvelle base.

Les sauvegardes

Le README précise que FreshRSS est fourni sans aucune garantie : vos sauvegardes gardent vos abonnements, vos articles et vos réglages. Voici ce que la documentation demande de sauvegarder :

Les volumes, service arrêté

La documentation juge plus sûr d'arrêter le service pendant les opérations de maintenance. Les volumes Docker se copient avec un conteneur temporaire, la méthode que décrit la documentation de 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

Les bases, service en marche

Depuis la version 1.29.1, FreshRSS sait exporter lui-même la base de chaque utilisateur dans un fichier SQLite, quelle que soit la base utilisée, et ne garder que les plus récents. Activez cet export dans data/config.php :

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

Puis planifiez la commande sur le serveur, ici chaque nuit. Chaque passage écrit data/users/<utilisateur>/sqlite-backups/<date>.sqlite et supprime les fichiers au-delà des sept derniers :

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

Avec PostgreSQL, ajoutez un export par l'outil de la base, comme dans le README Docker. L'option -T retire le terminal, dont une tâche planifiée n'a pas l'usage :

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

L'export OPML, depuis l'interface, sauvegarde la liste de vos flux, sans certains réglages propres à FreshRSS, comme les identifiants ou les règles d'extraction des pages. Pour une copie complète, gardez les exports SQLite : posés sur le disque du serveur, ils entrent aussi dans ses sauvegardes de nuit.

Restaurer

1. Arrêtez FreshRSS avec docker compose stop freshrss.
2. Rechargez l'archive dans les volumes : docker run --rm --volumes-from freshrss -v "$PWD":/backup ubuntu tar -xzf /backup/freshrss-AAAA-MM-JJ.tgz -C /var/www/FreshRSS.
3. Avec une base externe, restaurez-la depuis son export, ou depuis les fichiers SQLite avec cli/db-restore.php --delete-backup --force-overwrite.
4. Relancez avec docker compose start freshrss, puis vérifiez que vos flux et vos articles sont là.

Répétez cet exercice de temps en temps, sur une copie : c'est ainsi que vous vérifiez qu'une sauvegarde fonctionne.

Les mises à jour

Le README Docker donne deux commandes, depuis le dossier du compose.yaml. Les volumes restent en place :

docker compose pull
docker compose up -d

FreshRSS publie sur deux canaux. Les versions numérotées, étiquette latest, sortent quelques fois par an, sans calendrier fixe, et leurs correctifs ne sont pas reportés sur les versions plus anciennes. La version continue, étiquette edge, reçoit les nouveautés et les correctifs au fil de l'eau : depuis la version 1.30.0, le projet la recommande pour recevoir plus vite les correctifs de sécurité.

• Sauvegardez avant : la documentation demande une sauvegarde de data/, des extensions et de la base avant chaque mise à jour.
• Version par version : si vous avez plusieurs versions de retard, passez par chacune, par exemple de 1.26.0 à 1.27.1 avant 1.28.1, en vérifiant à chaque étape. Avec Docker, les étiquettes comme 1.29.1 rendent ce chemin possible.
• Les versions récentes : la 1.30.4 du 21 octobre 2026 est la quatrième version de sécurité de la série 1.30. Elle corrige des failles de PHP dans les images Alpine, après la 1.30.3, qui a porté l'image Debian par défaut sur Debian 13.

Pour suivre les sorties, le projet publie le flux Atom de ses versions : abonnez-y votre propre instance FreshRSS.

Qui fait quoi sur un VPS géré

L'auto-hébergement demande de tenir le serveur en plus de l'application. Sur un VPS géré, nos équipes prennent le serveur en main et suivent votre instance de manière proactive ; FreshRSS reste votre logiciel, avec ses réglages et ses données.

Si vous préférez que nos équipes interviennent dans l'application elle-même, cette prestation se facture à l'heure ou au forfait, avec un chiffrage communiqué avant l'intervention.