Ubuntu VPS uzerine FreshRSS kurulumu rehberi

Kurulan yapı

Self-hosted RSS okuyucu, sahibi olduğunuz bir sunucuda çalışan bir feed reader uygulamasıdır. Bu nedenle kimse uygulamayı kapatamaz veya size gösterilen içerikleri değiştiremez. Bu kılavuzda FreshRSS, Ubuntu 24.04 çalışan bir VPS üzerinde kurulmaktadır: Apache önde, PHP arka planda, depolama için MariaDB ve yeni makaleleri getiren tek bir cron işi kullanılacaktır. RSS (really simple syndication), bir sitenin makalelerini yazılımların okuyabilmesi için yayımladığı dosya biçimidir. FreshRSS, bu dosyaları toplayan, makaleleri saklayan ve web arayüzü ile telefon uygulamalarının kullandığı bir API (application programming interface) sağlayan PHP uygulamasıdır.

Kurulumun kendisi kısadır: bir release paketi açılır, bir veritabanı oluşturulur, bir virtual host yazılır, command line installer çalıştırılır ve cli/create-user.php ile hesap oluşturulur. Aşağıdaki işlemlerin çoğu, kurulumdan sonra sıklıkla yanlış yapılandırılan refresh job, mobile API için encoded slash ayarları ve dosya sahipliğidir.

21 Ekim 2026 tarihinde yayımlanan FreshRSS 1.30.4, 29 Ekim 2026 itibarıyla güncel release sürümüdür ve PHP 8.1 veya daha yeni bir sürüm gerektirir. Ubuntu 24.04, PHP 8.3 ile birlikte geldiğinden dağıtım paketleri yeterlidir; üçüncü taraf bir PHP repository kullanılmasına gerek yoktur.

Çalışan bir LAMP yığını ile başlayın

FreshRSS standart bir PHP uygulamasıdır, bu nedenle diğer tüm uygulamalarla aynı temel gereksinimlere sahiptir. Eğer bu temeli henüz oluşturmadıysanız, önce Ubuntu 24.04 üzerinde LAMP yığını kurulumu rehberini takip edin ve ardından buraya dönün. Kısa özet:

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

systemctl status apache2 komutu active (running) çıktısını vermelidir. Apache başlamıyorsa, bunun yaygın nedeni başka bir sürecin 80 numaralı portu kullanıyor olmasıdır; sudo ss -ltnp | grep :80 komutu bu süreci tanımlayacaktır.

FreshRSS için gerekli PHP eklentileri

FreshRSS; libxml, cURL, JSON, PDO_MySQL, PCRE ve ctype kütüphanelerini zorunlu tutar. Ayrıca mbstring, iconv, Zlib, ZipArchive ve 32 bit sistemlerde GMP eklentilerini de gerektirir. Ubuntu üzerinde bu paketler dağıtım paketleri olarak şu şekilde kurulur:

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

PHP'nin halihazırda neleri yüklediğini php -m ile kontrol edin. Eksik bir eklenti, yükleyicinin başlamasını engellemez. Yükleyiciyi, eksik eklentiyi belirten kırmızı bir satırla gereksinimler ekranında durdurur; bu, sorunu keşfetmek için kafa karıştırıcı bir noktadır, bu yüzden şimdi doğrulayın. Apache'yi yeniden başlatmak önemlidir çünkü libapache2-mod-php, PHP'yi Apache süreci içinde tutar; bu nedenle yeni yüklenen bir eklenti, sunucu yeniden başlatılana kadar web sunucusu tarafından görülmez.

Sürümü indirme

FreshRSS, varsayılan web kök dizininin dışında kurulmalı ve Apache bu dizini gösterecek şekilde yapılandırılmalıdır. Uygulama dizininin document root dizininden ayrı tutulması, HTTP üzerinden yalnızca public klasörüne erişilebilmesini sağlar.

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

Şimdi FreshRSS belgelerinde kesin olarak belirtilen izinler ayarlanmalıdır: web sunucusu kullanıcısı tüm dizin ağacının sahibi olmalı, grup her dosyayı okuyabilmeli ve ./data/ dizinine yazabilmelidir.

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

Bu adım atlanırsa yükleyici yapılandırma dosyasını yazarken başarısız olur. Bunun nedeni, PHP'nin www-data olarak çalışması ve www-data kullanıcısının root tarafından sahiplenilen bir dizine yazamamasıdır.

Veritabanını oluşturma

FreshRSS; SQLite, MariaDB, MySQL ve PostgreSQL destekler. SQLite için php-sqlite3 uzantısı gerekir, ancak veritabanı sunucusu kurulumu gerekmez. Her kullanıcının verileri ayrı bir data/users/_user_/db.sqlite dosyasında saklanır. Kullanıcı eklemek, verileri tek bir ortak SQLite dosyasına yazmaz. Bu kılavuzda LAMP yığınının bir parçası olarak MariaDB kullanılmaktadır.

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

utf8 yerine utf8mb4 kullanın. Akışlar emoji ve Latin alfabesi dışındaki yazı sistemlerini içerebilir. Eski üç baytlık utf8 kodlaması dört baytlık karakterleri saklayamaz. Desteklenmeyen karakterler, MariaDB'nin varsayılan strict mode ayarı altında hataya neden olur. Kırpma davranışı ise SQL mode ve IGNORE gibi ifade seçeneklerine bağlıdır.

Apache sanal ana bilgisayarı (virtual host)

Genel dizin p/ yolundadır, ağaç yapısının en üstünde değildir. Veritabanı parolanızı içeren yapılandırma dosyası dahil olmak üzere diğer her şey, Apache'nin asla sunmayacağı belge kök dizininin üzerinde yer alır.

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

Bunu /etc/apache2/sites-available/freshrss.conf olarak kaydedin ve etkinleştirin:

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

configtest komutu Syntax OK çıktısını vermelidir. AllowEncodedSlashes On isteğe bağlı görünebilir ancak değildir: Google Reader API, %2F karakterlerini içeren besleme tanımlayıcıları gönderir ve bu yönerge olmadan Apache bunları reddeder; bu durumda web arayüzü sorunsuz çalışırken mobil uygulamalar eşitleme yapamaz.

Oturum açmadan önce HTTPS ekleyin

Bu siteye bir parola girmek üzeresiniz, bu nedenle öncelikle bir sertifika edinin. Bir A kaydını sunucuya yönlendirin, ardından Ubuntu üzerinde Apache için Certbot kurulumu adımlarını izleyin ve sudo certbot --apache -d rss.example.com komutunu çalıştırın. Certbot, 443 numaralı port için sanal ana bilgisayar (virtual host) yapılandırmasını yeniden yazar ve yönlendirmeyi ekler. curl -I https://rss.example.com/ komutu ile doğrulamayı yapın; bu komut bir 200 yanıtı veya oturum açma sayfasına bir yönlendirme döndürmelidir.

Yükleyiciyi komut satırından çalıştırma

FreshRSS bir tarayıcı tabanlı yükleyiciye sahiptir, ancak komut satırı sürümü tekrarlanabilir bir yapıdadır ve seçilen ayarların tam bir kaydını tutar.

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'

Her iki komutu da www-data olarak çalıştırın. Komutların root olarak çalıştırılması, yapılandırma dosyalarının root sahipliğinde oluşturulmasına neden olur; bu durum, web arayüzünün daha sonra herhangi bir ayarı kaydetmesini engeller. --environment production ayarı da önemlidir, çünkü geliştirme modu etkinleştirildiğinde PHP uyarıları sayfa içeriğine yazdırılır.

https://rss.example.com/ dosyasını yükleyin ve admin olarak giriş yapın.

Beslemeler kendiliğinden neden yenilenmez

Siz belirtmedikçe hiçbir işlem beslemeleri yoklamaz. FreshRSS açıldığında beslemelerin alınması için zamanlanmış bir görev oluşturulmaz; scheduler yapılandırılmamışsa makaleleri manuel olarak almak için gezinme menüsündeki güncelleme bağlantısını kullanın. Çözüm, projenin bu amaçla sunduğu app/actualize_script.php betiğini cron üzerinden çalıştırmaktır.

sudo crontab -u www-data -e

Bir satır ekleyin:

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

Yirmi dakika makul bir zamanlamadır, ancak her beslemenin yenileme aralığı yine geçerlidir: varsayılan aralık bir saattir ve tek tek beslemeler için on beş dakikaya kadar kısa aralıklar desteklenir. Önce elle bir kez çalıştırın:

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

Sorunsuz çıktı, yenileme çalışmasının gerçekleştirildiğini bildirir ve bir PHP hatası olmadan sona erer; makaleler eklendiğinde veya güncellendiğinde besleme adları görünür. Hiçbir çıktı alınmıyorsa PHP hata çıktısını ve FreshRSS günlüklerini kontrol edin; tek başına sessiz çıktı, sorunun cron kullanıcısından kaynaklandığını göstermez. data/ üzerinde bir izin hatası alınırsa sahiplik ve yazma izinleri kontrol edilmelidir.

İlk beslemelerinizi ekleyin

Arayüzün sol üst köşesindeki artı düğmesini kullanın, bir site adresi yapıştırın; FreshRSS besleme bağlantısını sizin için otomatik olarak bulacaktır. Çoğu site, reklamını yapmasa bile genellikle /feed, /rss veya /atom.xml adreslerinde bir besleme yayınlar. Kategoriler klasör görevi görür ve bir beslemeyi bu klasörler arasında taşımak sürükle-bırak yöntemiyle yapılır.

Başka bir okuyucudan geçiş yapıyorsanız, oradan bir OPML dosyası dışa aktarın ve abonelik yönetimi sayfası altından içe aktarın. OPML (outline processor markup language), standart besleme listesi formatıdır ve terk etmeye değer her okuyucu bunu destekler. Büyük boyutlu bir içe aktarma işleminde, her besleme ilk kez getirileceği için ilk yenileme yavaş olacaktır; bu nedenle hız konusunda karar vermeden önce ilk cron çalışmasına zaman tanıyın.

Telefonunuzda okuyun

FreshRSS, birçok RSS uygulamasının desteklediği Google Reader API ile çalışır. İki koşulun sağlanması gerekir. Kimlik doğrulama ayarlarında "API erişimine izin ver" seçeneği açık olmalıdır; yukarıdaki --api-enabled flag'i bunu zaten etkinleştirmiştir. Profilinizde API password alanında bir değer bulunmalıdır. Bu alan, telefonun kaybedilmesi daha kolay bir cihaz olması nedeniyle giriş password'ünden kasıtlı olarak ayrı tutulur.

Sunucu yapılandırma kontrollerini otomatik olarak çalıştırmak için https://rss.example.com/api/ adresini ziyaret edin. Çalışan bir kurulum PASS döndürür. Kontrol başarısız olursa virtual host'un AllowEncodedSlashes On ayarını ve bildirilen hatayı kontrol edin. Uygulamada sunucu adresi olarak https://rss.example.com/api/greader.php, kullanıcı adı olarak FreshRSS kullanıcı adınızı ve password olarak API password'ünü girin.

Docker alternatifi

PHP ve Apache servislerini manuel olarak yönetmek istemiyorsanız, proje resmi bir freshrss/freshrss imajı yayınlamaktadır ve tek bir compose dosyası ile uygulama ve veritabanı birlikte kurulabilir. Bu durumun getirdiği takas standarttır: ana makinede daha az hareketli parça bulunur, ancak bir sorun çıktığında hata ayıklanacak bir katman daha eklenmiş olur ve TLS (transport layer security) için yine de bir reverse proxy gereklidir. Eğer bu yöntem size daha uygunsa, VPS üzerinde Docker Compose temelleri dokümanı dosya formatını açıklar ve cron satırı docker exec --user www-data freshrss php ./app/actualize_script.php haline gelir.

Yedeklemeler ve yükseltmeler

Sunucu durumunuzu iki unsur belirler: veritabanı ve /srv/freshrss/data/. İlkini sudo mysqldump freshrss > freshrss.sql ile dışa aktarın, ikincisini kopyalayın ve her ikisini de bu sunucunun dışında bir yerde saklayın. Abonelik listeniz için de zaman zaman OPML dışa aktarımı yapmak faydalıdır; bu dosya, besleme listenizi OPML destekleyen diğer okuyuculara aktarmanızı sağlar. Bu işlem; yenileme sıklığı, kimlik bilgileri, user agent veya XPath web kazıma kuralları gibi FreshRSS'e özgü ayarları korumaz; bunları da saklamak için bir SQLite dışa aktarımı kullanın.

Yükseltme işlemi, daha yeni bir sürümü mevcut dizinin üzerine açmak ve sahiplik komutlarını yeniden çalıştırmaktan ibarettir. Projenin sürümden sürüme yükseltme yolunu izleyin ve her adımdan sonra FreshRSS'i doğrulayın. FreshRSS, bir sonraki sayfa yüklemesinde kendi veritabanı migrasyonlarını uygular. Önce yedekleme yapın, çünkü geri yükleyemeyeceğiniz bir veritabanında başarısız olan bir migrasyon, kurtarılamaz bir durumdur. Eğer 1.29.1 gibi eski bir tarball dosyasından kurulum yaptıysanız, 1.30.4 sürümüne geçin: 1.30.x güvenlik sürümleri, kimlik doğrulama değişikliklerinde session ID rotasyonu ve ZIP içe aktarmaları için sınırlar içerir; 1.30.4 sürümü ayrıca kritik PHP güvenlik açıkları için alternatif Alpine Docker imajlarını günceller. Bir RSS okuyucu, çalıştırılması düşük riskli bir servistir ve eğer kendi sunucunuzda barındırmaya değer servisler listesi üzerinde çalışıyorsanız, başlangıç için iyi bir adaydır.

FAQ

Beslemelerim neden yalnızca FreshRSS'yi açtığımda güncelleniyor?

Sayfanın açılması besleme çekme işlemini zamanlamaz. Bir zamanlayıcı yoksa beslemeleri elle yenilemek için güncelleme bağlantısını kullanın. www-data kullanıcısı olarak app/actualize_script.php komutunu çağıran cron satırını ekleyin. Ardından betiği bir kez elle çalıştırın ve çıktısını okuyun. Çıktı yoksa PHP hata çıktısını ve FreshRSS günlüklerini kontrol edin. Cron kullanıcısının data/ konumuna yazma izni olduğunu da doğrulayın.

Mobil uygulamam bağlanamıyor, ancak web sitesi çalışıyor. Neden?

Google Reader API, istek yollarının içinde kodlanmış eğik çizgiler (%2F) kullanır. Apache bunları varsayılan olarak reddeder. Sanal host içine AllowEncodedSlashes On ekleyin ve Apache'yi yeniden yükleyin. Düzeltmeyi https://rss.example.com/api/ adresini açarak doğrulayın. Otomatik yapılandırma denetimi burada PASS bildirmelidir. API parolasının profilinizde ayarlandığını da kontrol edin. Bu parola, giriş parolanızdan ayrıdır.

SQLite mı yoksa MariaDB mi kullanılmalı?

SQLite için php-sqlite3 eklentisi gerekir. Ancak yönetilecek bir veritabanı sunucusu veya veritabanı parolası gerekmez. Her kullanıcıya ayrı bir SQLite veritabanı dosyası verilir. Bu nedenle ikinci bir kullanıcı eklemek, ortak tek bir dosyada çakışmaya yol açmaz ve MariaDB gerektirmez. LAMP yığınınızdaki veritabanı sunucusunu kullanmak istiyorsanız MariaDB kullanın. Daha sonra dışa aktarma ve içe aktarma komutlarıyla diğerine geçilebilir. Bu nedenle kalıcı bir karar değildir.

Yükleyici yapılandırma dosyasını yazarken başarısız oluyor. Sorun nedir?

Apache altında PHP, www-data olarak çalışır. Bu kullanıcı, root tarafından sahip olunan bir dizine yazamaz. sudo chown -R www-data:www-data /srv/freshrss ve sudo chmod -R g+w /srv/freshrss/data komutlarını yeniden çalıştırın. Ardından yükleyiciyi tekrar başlatın. Komut satırı yükleyicisini daha önce root olarak çalıştırdıysanız yeniden denemeden önce data/ altında oluşturduğu dosyaların sahipliğini düzeltin.

Self-hosted bir RSS okuyucusu ne kadar sunucu kaynağı gerektirir?

Çok az kaynak gerektirir. FreshRSS mütevazı donanımlarda çalışacak şekilde tasarlanmıştır. Ancak kaynak kullanımı beslemelerinize, makale boyutlarına ve saklama ayarlarına bağlıdır. Saklama süresi uzadıkça disk kullanımı artar. Bu nedenle her şeyi süresiz saklamak yerine arşivleme ayarlarında makale temizleme politikası belirleyin.