Installer FreshRSS sur un VPS Ubuntu avec Apache

Ce que vous allez installer

Un lecteur RSS auto-hébergé est un lecteur de flux qui s’exécute sur un serveur que vous administrez. Personne ne peut donc l’arrêter ni modifier ce qu’il vous affiche. Ce guide installe FreshRSS sur un VPS Ubuntu 24.04 : Apache en frontal, PHP en backend, MariaDB pour le stockage et une tâche cron qui récupère les nouveaux articles. RSS (really simple syndication) désigne le format de fichier qu’un site publie pour permettre à des logiciels de lire ses articles. FreshRSS est l’application PHP qui collecte ces fichiers, conserve les articles et fournit une interface web ainsi qu’une API (application programming interface) utilisée par les applications mobiles.

L’installation est simple : décompresser une release, créer une base de données, écrire un virtual host, exécuter l’installateur en ligne de commande, puis créer le compte avec cli/create-user.php. La plupart des erreurs surviennent ensuite, notamment avec la tâche de rafraîchissement, les encoded slashes nécessaires à l’API mobile et le propriétaire des fichiers.

FreshRSS 1.30.4, publié le 21 octobre 2026, est la release actuelle au 29 octobre 2026. Il nécessite PHP 8.1 ou une version ultérieure. Ubuntu 24.04 fournit PHP 8.3 : les paquets de la distribution suffisent et vous n’avez pas besoin d’un dépôt PHP tiers.

Partir d’une pile LAMP opérationnelle

FreshRSS est une application PHP classique. Elle nécessite donc la même base que les autres applications PHP. Si cette base n’est pas encore en place, suivez d’abord la procédure de configuration d’une pile LAMP sur Ubuntu 24.04, puis revenez ici. En résumé :

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

systemctl status apache2 doit renvoyer active (running). Si Apache ne démarre pas, la cause habituelle est qu’un autre processus utilise déjà le port 80. sudo ss -ltnp | grep :80 l’identifie.

Les extensions PHP nécessaires à FreshRSS

FreshRSS considère libxml, cURL, JSON, PDO_MySQL, PCRE et ctype comme obligatoires. Il recommande également mbstring, iconv, Zlib et ZipArchive, ainsi que GMP sur un système 32 bits. Sur Ubuntu, elles sont fournies par les paquets de la distribution :

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

Vérifiez les extensions effectivement chargées par PHP avec php -m. L’absence d’une extension n’empêche pas le programme d’installation de démarrer. Elle bloque l’installation sur l’écran des prérequis, avec une ligne rouge indiquant le nom de l’extension. Il est donc préférable de vérifier maintenant, car cet écran est un endroit peu clair pour découvrir le problème. Le redémarrage d’Apache est nécessaire, car libapache2-mod-php conserve PHP dans le processus Apache. Le serveur web ne voit donc pas une extension nouvellement installée tant qu’il n’a pas redémarré.

Télécharger la release

Installez FreshRSS en dehors du web root par défaut, puis configurez Apache pour y accéder. En séparant le répertoire de l’application du document root, seul le dossier public est accessible via HTTP.

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

Passons aux permissions, auxquelles la documentation de FreshRSS est stricte : l’utilisateur du serveur web possède l’arborescence, le groupe peut lire tous les fichiers et peut écrire dans ./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

Si vous ignorez cette étape, l’installateur échoue lors de l’écriture de sa configuration, car PHP s’exécute avec www-data et www-data ne peut pas écrire dans un répertoire appartenant à root.

Créer la base de données

FreshRSS prend en charge SQLite, MariaDB, MySQL et PostgreSQL. SQLite nécessite l’extension php-sqlite3, mais pas la configuration d’un serveur de base de données. Il stocke les données de chaque utilisateur dans un fichier data/users/_user_/db.sqlite distinct. Ajouter des utilisateurs n’écrit pas leurs données dans un fichier SQLite partagé. Ce guide utilise MariaDB dans le cadre de la pile 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;"

Utilisez utf8mb4 et non utf8. Les flux contiennent des emoji et des scripts non latins. L’ancien encodage utf8 sur trois octets ne peut pas stocker les caractères sur quatre octets. Les caractères non pris en charge provoquent une erreur avec le mode strict par défaut de MariaDB. La troncature dépend du mode SQL et d’options de l’instruction telles que IGNORE.

L’hôte virtuel Apache

Le répertoire public est p/, et non la racine de l’arborescence. Tout le reste, notamment le fichier de configuration qui contient le mot de passe de votre base de données, se trouve au-dessus de la racine des documents. Apache ne le servira jamais.

<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>

Enregistrez ce contenu dans /etc/apache2/sites-available/freshrss.conf, puis activez-le :

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

configtest devrait afficher Syntax OK. AllowEncodedSlashes On semble facultative, mais elle est nécessaire : l’API Google Reader envoie des identifiants de flux contenant %2F. Sans cette directive, Apache les rejette. Les applications mobiles ne peuvent donc pas se synchroniser, alors que l’interface web fonctionne correctement.

Ajoutez HTTPS avant de vous connecter

Vous êtes sur le point de saisir un mot de passe sur ce site. Obtenez donc d’abord un certificat. Faites pointer un enregistrement A vers le serveur, puis suivez la procédure de configuration de Certbot pour Apache sur Ubuntu et exécutez sudo certbot --apache -d rss.example.com. Certbot réécrit l’hôte virtuel pour le port 443 et ajoute la redirection. Vérifiez avec curl -I https://rss.example.com/, qui doit renvoyer un 200 ou rediriger vers la page de connexion.

Exécuter l’installateur depuis la ligne de commande

FreshRSS propose un installateur dans le navigateur, mais la version en ligne de commande est reproductible et conserve la trace exacte de vos choix.

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'

Exécutez les deux commandes avec www-data. Si vous les exécutez en tant que root, les fichiers de configuration appartiennent à root. L’interface Web ne pourra alors plus enregistrer les paramètres. --environment production est également important, car le paramètre de développement affiche les notifications PHP dans la page.

Chargez https://rss.example.com/ et connectez-vous en tant que admin.

Pourquoi les flux ne se mettent pas à jour automatiquement

Aucun processus n’interroge vos flux tant que vous ne l’avez pas configuré. L’ouverture de FreshRSS ne planifie pas la récupération des flux. Sans scheduler, utilisez le lien de mise à jour dans le menu de navigation pour récupérer les articles manuellement. La solution consiste à utiliser le script fourni par le projet à cet effet, app/actualize_script.php, exécuté depuis cron.

sudo crontab -u www-data -e

Ajoutez une ligne :

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

Une exécution toutes les vingt minutes constitue un réglage raisonnable, mais l’intervalle de mise à jour propre à chaque flux reste appliqué : la valeur par défaut est d’une heure, et les flux individuels acceptent des intervalles allant jusqu’à quinze minutes. Exécutez d’abord le script manuellement :

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

Une sortie normale indique l’exécution de la mise à jour et se termine sans erreur PHP. Les noms des flux apparaissent lorsque des articles sont ajoutés ou mis à jour. Si aucune sortie ne s’affiche, vérifiez les messages d’erreur de PHP et les journaux de FreshRSS. Le silence ne permet pas à lui seul d’identifier l’utilisateur de cron comme étant à l’origine du problème. Une erreur de permission sur data/ impose de vérifier le propriétaire et les permissions d’écriture.

Ajouter vos premiers flux

Utilisez le bouton plus en haut à gauche de l’interface, collez l’adresse d’un site et FreshRSS détecte le lien du flux pour vous. La plupart des sites en publient encore un même lorsqu’ils ne l’affichent pas, généralement à l’adresse /feed, /rss ou /atom.xml. Les catégories sont des dossiers. Pour déplacer un flux entre deux catégories, faites-le glisser.

Si vous utilisez un autre lecteur, exportez-y un fichier OPML, puis importez-le depuis la page de gestion des abonnements. OPML (outline processor markup language) est le format standard des listes de flux, et tout lecteur qui mérite d’être utilisé prend en charge ce format. Une importation volumineuse est lente lors de la première actualisation, car chaque flux est récupéré une fois. Laissez donc le premier lancement de cron se terminer avant d’évaluer la vitesse.

Lisez vos flux sur votre téléphone

FreshRSS prend en charge l’API Google Reader, que de nombreuses applications RSS utilisent. Deux conditions doivent être réunies. Dans les paramètres d’authentification, l’option « Allow API access » doit être activée ; le flag --api-enabled ci-dessus l’a déjà définie. Dans votre profil, le champ du mot de passe API doit contenir une valeur. Il est volontairement distinct de votre mot de passe de connexion, car un téléphone est plus facile à perdre.

Accédez à https://rss.example.com/api/ pour exécuter automatiquement les vérifications de configuration du serveur. Une configuration fonctionnelle renvoie PASS. Si la vérification échoue, contrôlez le paramètre AllowEncodedSlashes On du virtual host et l’erreur signalée. Dans l’application, indiquez https://rss.example.com/api/greader.php comme adresse du serveur, votre utilisateur FreshRSS comme nom d’utilisateur et le mot de passe API comme mot de passe.

L’alternative Docker

Si vous préférez ne pas gérer PHP et Apache manuellement, le projet publie une image officielle freshrss/freshrss. Un fichier Compose suffit pour déployer l’application et sa base de données ensemble. Le compromis est classique : moins de composants à gérer sur l’hôte, mais une couche supplémentaire à diagnostiquer en cas de problème. Un reverse proxy reste nécessaire pour TLS (transport layer security). Si cette solution vous convient mieux, les bases de Docker Compose pour un VPS expliquent le format du fichier. La ligne cron devient alors docker exec --user www-data freshrss php ./app/actualize_script.php.

Sauvegardes et mises à niveau

Deux éléments contiennent votre état : la base de données et /srv/freshrss/data/. Exportez la première avec sudo mysqldump freshrss > freshrss.sql, copiez le second, puis conservez les deux ailleurs que sur ce serveur. Votre liste d’abonnements mérite également un export OPML occasionnel, car ce fichier permet de transférer votre liste de flux vers d’autres lecteurs compatibles avec OPML. Il ne conserve pas les paramètres propres à FreshRSS, comme la fréquence d’actualisation, les identifiants, le user agent ou les règles de web scraping XPath ; utilisez un export SQLite pour les préserver également.

La mise à niveau consiste à décompresser une version plus récente dans le même répertoire, puis à réexécuter les commandes de ownership. Suivez le chemin de mise à niveau indiqué par le projet, version par version, et vérifiez FreshRSS après chaque étape. FreshRSS applique ses propres migrations de base de données au chargement de la page suivante. Effectuez d’abord une sauvegarde, car une migration échouée sur une base de données que vous ne pouvez pas restaurer vous placerait dans une situation irrécupérable. Si vous avez installé une ancienne archive tar, comme 1.29.1, passez à 1.30.4 : les versions de sécurité 1.30.x incluent la rotation des identifiants de session lors des modifications d’authentification et des limites pour les imports ZIP, tandis que 1.30.4 met également à jour les images Docker Alpine alternatives pour corriger de graves vulnérabilités PHP. Un lecteur est un service peu risqué à exécuter et constitue un bon premier candidat si vous examinez la liste des services qui méritent d’être auto-hébergés.

FAQ

Pourquoi mes flux ne se mettent-ils à jour que lorsque j’ouvre FreshRSS ?

L’ouverture de la page ne planifie pas la récupération des flux. Sans scheduler, utilisez le lien de mise à jour pour actualiser les flux manuellement. Ajoutez la ligne cron qui appelle app/actualize_script.php en tant qu’utilisateur www-data, puis exécutez le script manuellement une fois et lisez sa sortie. Si aucune sortie ne s’affiche, vérifiez les erreurs PHP et les journaux FreshRSS, puis confirmez que l’utilisateur cron dispose d’un accès en écriture à data/.

Mon application mobile ne peut pas se connecter, mais le site fonctionne. Pourquoi ?

L’API Google Reader utilise des slashs encodés (%2F) dans les chemins des requêtes, et Apache les rejette par défaut. Ajoutez AllowEncodedSlashes On dans le virtual host, puis rechargez Apache. Confirmez la correction en ouvrant https://rss.example.com/api/ : le contrôle de configuration automatique doit indiquer PASS. Vérifiez également que le mot de passe de l’API est défini dans votre profil, car il est distinct de votre mot de passe de connexion.

Dois-je utiliser SQLite ou MariaDB ?

SQLite nécessite l’extension php-sqlite3, mais ne demande ni serveur de base de données ni mot de passe de base de données à gérer. Chaque utilisateur dispose d’un fichier de base de données SQLite distinct. L’ajout d’un deuxième utilisateur ne crée donc pas de contention sur un fichier partagé et ne nécessite pas MariaDB. Utilisez MariaDB si vous souhaitez exploiter le serveur de base de données de votre stack LAMP. Il est possible de migrer ultérieurement de l’un à l’autre avec les commandes d’export et d’import. Ce choix n’est donc pas définitif.

L’installateur échoue lorsqu’il écrit sa configuration. Quelle est la cause ?

PHP s’exécute sous Apache avec l’utilisateur www-data, qui ne peut pas écrire dans un répertoire appartenant à root. Réexécutez sudo chown -R www-data:www-data /srv/freshrss et sudo chmod -R g+w /srv/freshrss/data, puis relancez l’installateur. Si vous avez déjà exécuté l’installateur en ligne de commande avec root, corrigez le propriétaire des fichiers qu’il a créés sous data/ avant de réessayer.

De quelles ressources serveur un lecteur RSS auto-hébergé a-t-il besoin ?

De très peu. FreshRSS est conçu pour fonctionner sur une configuration matérielle modeste, mais l’utilisation des ressources dépend de vos flux, de la taille des articles et des paramètres de conservation. L’espace disque augmente avec la durée de conservation. Définissez donc une règle de purge des articles dans les paramètres d’archivage au lieu de tout conserver indéfiniment.