Jinsi ya kusakinisha FreshRSS kwenye Ubuntu VPS

Unachojenga

RSS reader inayojiendesha (self-hosted) ni kisoma-feeds kinachofanya kazi kwenye seva unayomiliki, hivyo hakuna mtu anayeweza kuizima au kubadilisha kile inachokuonyesha. Mwongozo huu unaweka FreshRSS kwenye Ubuntu 24.04 VPS: Apache mbele, PHP nyuma yake, MariaDB kwa ajili ya kuhifadhi data, na cron job moja inayochota makala mpya. RSS (Really Simple Syndication) ni muundo wa faili ambao tovuti huchapisha ili programu iweze kusoma makala zake. FreshRSS ni programu ya PHP inayokusanya faili hizo, kuhifadhi makala, na kukupa kiolesura cha wavuti pamoja na API (Application Programming Interface) inayotumiwa na programu za simu.

Ufungaji wenyewe ni mdogo: toa faili kwenye archive, tengeneza database, andika virtual host moja, na uendeshe kisakinishi cha mstari wa amri (command line). Kazi nyingi hapa chini ni sehemu ambayo watu hukosea baadaye, ambayo ni kazi ya kusasisha (refresh job), slashes zilizosimbwa kwa ajili ya API ya simu, na umiliki wa faili.

FreshRSS 1.29.1 ndiyo toleo la sasa kufikia Julai 2026, na linahitaji PHP 8.1 au mpya zaidi. Ubuntu 24.04 inakuja na PHP 8.3, kwa hivyo vifurushi vya usambazaji (distribution packages) vinatosha na huhitaji hazina (repository) ya PHP ya mtu wa tatu.

Anza na LAMP stack inayofanya kazi

FreshRSS ni programu ya kawaida ya PHP, kwa hivyo inahitaji msingi uleule kama programu nyingine yoyote. Ikiwa bado hujajenga msingi huo, fuata usanidi wa LAMP stack kwa Ubuntu 24.04 kwanza kisha urudi hapa. Toleo fupi:

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

systemctl status apache2 inapaswa kutoa taarifa ya active (running). Ikiwa Apache itakataa kuanza, sababu ya kawaida ni mchakato mwingine ambao tayari unashikilia port 80, na sudo ss -ltnp | grep :80 itautaja mchakato huo.

Viendelezi vya PHP vinavyohitajika na FreshRSS

FreshRSS inachukulia libxml, cURL, JSON, PDO_MySQL, PCRE na ctype kama vitu vya lazima. Pia inahitaji mbstring, iconv, Zlib na ZipArchive, pamoja na GMP kwenye mfumo wa 32-bit. Kwenye Ubuntu, hivi vinapatikana kama vifurushi vya usambazaji:

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

Thibitisha ni viendelezi vipi vya PHP vilivyopakiwa kwa kutumia php -m. Kiendelezi kinachokosekana hakizuii kisakinishi kuanza. Kinakizuia kwenye skrini ya mahitaji kwa mstari mwekundu unaotaja kiendelezi hicho, hali inayoweza kuchanganya unapogundua tatizo, kwa hivyo thibitisha sasa. Kuanzisha upya Apache ni muhimu kwa sababu libapache2-mod-php huweka PHP ndani ya mchakato wa Apache, hivyo kiendelezi kipya kilichosakinishwa hakitaonekana na seva ya wavuti hadi itakapoanzishwa upya.

Pakua toleo husika

Sakinisha FreshRSS nje ya saraka ya msingi ya wavuti (web root), kisha uelekeze Apache kwenye saraka hiyo. Kuweka saraka ya programu kando na document root kunahakikisha kuwa folda ya public pekee ndiyo inayoweza kufikiwa kupitia HTTP.

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

Sasa kuhusu ruhusa (permissions), ambazo nyaraka za FreshRSS huzisisitiza sana: mtumiaji wa seva ya wavuti anapaswa kumiliki mti wa saraka, kundi (group) liweze kusoma kila faili, na kundi liweze kuandika kwenye ./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

Ukikwepa hatua hii, kisakinishi kitashindwa kuandika usanidi wake, kwa sababu PHP huendeshwa kama www-data na www-data haiwezi kuandika kwenye saraka inayomilikiwa na root.

Unda database

FreshRSS inasaidia SQLite, MariaDB, MySQL na PostgreSQL. SQLite haihitaji usanidi wowote na inafaa kwa mtumiaji mmoja mwenye feeds chache. MariaDB ni chaguo bora zaidi wakati watu kadhaa wanatumia instance moja, kwa sababu uandishi wa wakati mmoja kutoka kwa kazi ya refresh na interface ya wavuti haugombanii tena lock ya faili moja.

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

Tumia utf8mb4 na si utf8. Feeds hubeba emoji na maandishi yasiyo ya Kilatini, na encoding ya zamani ya byte tatu ya utf8 hukata kichwa cha habari kwenye herufi ya kwanza ya byte nne.

Virtual host ya Apache

Saraka ya umma ni p/, si sehemu ya juu ya mti wa faili. Kila kitu kingine, ikiwemo faili la usanidi lenye nenosiri la database yako, hukaa juu ya document root ambapo Apache haitakihudumia kamwe.

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

Hifadhi hiyo kama /etc/apache2/sites-available/freshrss.conf na uiwezeshe:

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

configtest inapaswa kuonyesha Syntax OK. AllowEncodedSlashes On inaonekana kama ya hiari lakini si hivyo: Google Reader API hutuma vitambulishi vya feed vyenye %2F, na bila maelekezo haya Apache huvikataa, hivyo programu za simu hushindwa kusawazisha (sync) wakati interface ya wavuti ikifanya kazi kikamilifu.

Ongeza HTTPS kabla ya kuingia kwenye mfumo

Unakaribia kuingiza nenosiri kwenye tovuti hii, kwa hivyo pata cheti kwanza. Elekeza A record kwenye seva, kisha fuata usanidi wa Certbot kwa Apache kwenye Ubuntu na uendeshe sudo certbot --apache -d rss.example.com. Certbot huandika upya virtual host kwa ajili ya port 443 na kuongeza redirect. Thibitisha kwa curl -I https://rss.example.com/, ambayo inapaswa kurejesha 200 au kuelekeza kwenye ukurasa wa kuingia.

Endesha kisakinishi kupitia mstari wa amri

FreshRSS ina kisakinishi cha kivinjari, lakini toleo la mstari wa amri linaweza kurudiwa na huacha kumbukumbu kamili ya chaguo ulizofanya.

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'

Endesha zote mbili kama www-data. Kuziendesha kama root hutengeneza faili za usanidi zinazomilikiwa na root, na kiolesura cha wavuti kitashindwa kuhifadhi mipangilio yoyote baadaye. --environment production ni muhimu pia, kwa sababu mpangilio wa development huchapisha notisi za PHP kwenye ukurasa.

Pakia https://rss.example.com/ na uingie kama admin.

Kwa nini feeds hazijisasishi zenyewe

Hakuna kinachofuatilia (poll) feeds zako hadi utakapokiamuru. FreshRSS hujisasisha wakati kivinjari kimefunguliwa kwenye ukurasa wake, jambo linalomaanisha kuwa instance unayotembelea mara mbili kwa siku itakuonyesha makala zilizopitwa na wakati kwa saa kumi na mbili. Suluhisho ni script ambayo mradi huu hutoa kwa ajili ya kazi hii, app/actualize_script.php, inayotekelezwa kupitia cron.

sudo crontab -u www-data -e

Ongeza mstari mmoja:

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

Dakika 20 ndio muda mfupi zaidi unaofaa, kwa sababu script hukataa kusasisha feed yoyote mara nyingi zaidi ya mara moja kila baada ya dakika ishirini, hivyo ratiba fupi zaidi itatumia CPU bila sababu. Iendeshe mara moja kwa mkono kwanza:

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

Matokeo mazuri (healthy output) yataorodhesha kila feed iliyochukuliwa na kuishia bila error ya PHP. Ikiwa haitoi chochote, mtumiaji wa cron si sahihi, na error ya permission kwenye data/ inamaanisha kuwa hatua ya chmod -R g+w ilirukwa.

Ongeza feeds zako za kwanza

Tumia kitufe cha kujumlisha kilicho upande wa juu kushoto wa kiolesura, bandika anwani ya tovuti, na FreshRSS itakutafutia kiungo cha feed. Tovuti nyingi bado huchapisha feed hata kama hazitangazi, kwa kawaida kwenye /feed, /rss au /atom.xml. Kategoria ni folda, na kuhamisha feed kati ya kategoria hizo ni rahisi kwa kuburuta.

Ikiwa unatoka kwenye kisomaji kingine, hamisha faili ya OPML kutoka huko na uingize kwenye ukurasa wa usimamizi wa usajili. OPML (outline processor markup language) ndiyo fomati ya kawaida ya orodha ya feeds, na kila kisomaji kinachofaa kutumiwa kinaunga mkono fomati hii. Uingizaji mkubwa wa data huwa polepole wakati wa refresh ya kwanza kwa sababu kila feed huchotwa mara moja, kwa hivyo ipe muda cron run ya kwanza kabla ya kuhukumu kasi yake.

Isome kwenye simu yako

FreshRSS inatumia Google Reader API, ambayo karibu kila programu ya RSS inaiunga mkono. Mambo mawili lazima yawe sawa. Chini ya mipangilio ya uthibitishaji (authentication settings), "Allow API access" lazima iwe imewashwa, jambo ambalo flag ya --api-enabled hapo juu tayari imetekeleza. Chini ya wasifu wako, sehemu ya API password lazima iwe na thamani, na hii imetenganishwa kimakusudi na nenosiri lako la kuingia kwa sababu simu ni kifaa rahisi kupotea.

Tembelea https://rss.example.com/api/ na uchague "Check full server configuration". Usanidi unaofanya kazi vizuri utarejesha PASS. Kushindwa hapa mara nyingi kunatokana na kukosekana kwa mstari wa AllowEncodedSlashes On. Kwenye programu, weka anwani ya seva kama https://rss.example.com/api/greader.php, jina la mtumiaji kama mtumiaji wako wa FreshRSS, na nenosiri la API kama nenosiri lako.

Mbadala wa Docker

Ikiwa ungependelea kutotunza PHP na Apache kwa mikono, mradi huu hutoa image rasmi ya freshrss/freshrss, na faili moja ya compose hukupa programu hiyo pamoja na database yake. Makubaliano ni yale ya kawaida: vipengele vichache vinavyohitaji matunzo kwenye host, safu moja zaidi ya kutatua matatizo (debug) kitu kinapoharibika, na bado unahitaji reverse proxy kwa ajili ya TLS (transport layer security). Ikiwa hilo linakufaa zaidi, misingi ya Docker Compose kwa VPS inashughulikia muundo wa faili, na mstari wa cron unakuwa docker exec --user www-data freshrss php ./app/actualize_script.php.

Hifadhi nakala na maboresho

Vitu viwili vinashikilia hali yako: database, na /srv/freshrss/data/. Fanya dump ya kwanza kwa kutumia sudo mysqldump freshrss > freshrss.sql, nakili ya pili, na uweke zote mbili mahali pengine nje ya seva hii. Orodha yako ya usajili pia inafaa kusafirishwa mara kwa mara kama OPML, kwa sababu faili hilo hujenga upya usanidi wako wa usomaji kwenye programu yoyote ya RSS.

Kuboresha ni kufungua release mpya juu ya saraka ileile na kuendesha upya amri za umiliki. FreshRSS hutekeleza migrations zake za database wakati wa kupakia ukurasa unaofuata. Hifadhi nakala kwanza, kwa sababu migration iliyofeli kwenye database ambayo huwezi kuirejesha ni hali isiyoweza kutatulika. Msomaji ni huduma yenye hatari ndogo ya kuendesha na mgombea mzuri wa kwanza ikiwa unafanya kazi kupitia orodha ya vitu vinavyofaa kujihifadhia mwenyewe.

FAQ

Kwa nini feeds zangu zinasasishwa tu ninapofungua FreshRSS?

Kwa sababu hakuna scheduler iliyopo hadi utakapoiunda. FreshRSS husasisha feeds wakati session ya kivinjari iko wazi na haifanyi chochote tab ikiwa imefungwa. Ongeza mstari wa cron unaoita app/actualize_script.php kama mtumiaji www-data, kisha endesha script hiyo kwa mkono mara moja na usome matokeo yake. Ukimya mara nyingi humaanisha cron inaiendesha kama mtumiaji asiye sahihi, hivyo PHP haiwezi kuandika kwenye data/.

App yangu ya simu haiwezi kuunganishwa, lakini tovuti inafanya kazi. Kwa nini?

Google Reader API huweka slashes zilizosimbwa (%2F) ndani ya njia za ombi (request paths), na Apache hukataa hizo kwa chaguo-msingi. Ongeza AllowEncodedSlashes On ndani ya virtual host na uanzishe upya Apache. Thibitisha marekebisho hayo kwa kufungua https://rss.example.com/api/ na kuendesha "Check full server configuration", ambayo inapaswa kuripoti PASS. Pia hakikisha nenosiri la API limewekwa kwenye profile yako, kwa sababu ni tofauti na nenosiri lako la kuingia.

Je, nitumie SQLite au MariaDB?

Tumia SQLite kwa mtumiaji mmoja, kwa sababu hakuna cha kusakinisha na hakuna nenosiri la kusimamia. Tumia MariaDB ikiwa zaidi ya mtu mmoja anasoma kwenye instance hiyo, au ukishapita mamia kadhaa ya feeds, kwa sababu kazi ya kusasisha na interface ya wavuti huandika kwa wakati mmoja na kufuli la faili moja huwa kikwazo. Kuhama kati ya hizi baadaye inawezekana kupitia amri za export na import, kwa hivyo huu si uamuzi wa kudumu.

Kisakinishi kinashindwa wakati kinaandika configuration yake. Nini tatizo?

PHP huendeshwa kama www-data chini ya Apache, na mtumiaji huyo hawezi kuandika kwenye saraka inayomilikiwa na root. Endesha tena sudo chown -R www-data:www-data /srv/freshrss na sudo chmod -R g+w /srv/freshrss/data, kisha anza kisakinishi tena. Ikiwa tayari uliendesha kisakinishi cha mstari wa amri kama root, futa faili ilizounda chini ya data/ kabla ya kujaribu tena, kwa sababu umiliki wao ndio tatizo halisi.

RSS reader inayojiendesha yenyewe inahitaji seva ya ukubwa gani?

Kidogo sana. Mamia kadhaa ya feeds kwenye mpango mdogo ni sawa, kwa sababu mzigo ni milipuko mifupi ya HTTP fetching kila baada ya dakika ishirini na database hubaki ndogo makala za zamani zikishafutwa. Disk hukua kulingana na uhifadhi, kwa hivyo weka sera ya kufuta makala kwenye mipangilio ya archiving badala ya kuhifadhi kila kitu milele.