Hosting FreshRSS na Managed VPS: Państwa kanały RSS na Państwa serwerze

Co robi FreshRSS

FreshRSS to samodzielnie hostowany agregator kanałów RSS napisany w PHP. README opisuje go jako lekki, łatwy w obsłudze, wydajny i konfigurowalny, przetłumaczony na ponad dwadzieścia języków. To aplikacja wieloużytkownikowa, z trybem czytania anonimowego i własnymi etykietami.

• Czytanie: subskrypcje uporządkowane w kategorie, etykiety, ulubione i zapisane wyszukiwania.
• WebSub: FreshRSS natychmiast otrzymuje nowe artykuły ze zgodnych źródeł, które same je przesyłają, zamiast czekać na następne odświeżenie.
• Pobieranie ze stron: w przypadku witryny bez kanału RSS ani Atom FreshRSS sam odczytuje stronę za pomocą reguł XPath, a potrafi też czytać dokumenty JSON.
• Udostępnianie: wybrane artykuły można ponownie opublikować w HTML, RSS lub OPML.
• Aplikacje: API dla aplikacji mobilnych i komputerowych, interfejs wiersza poleceń i rozszerzenia.

FreshRSS jest rozwijany przez swoją społeczność na GitHubie, a jego oficjalną stronę publikuje społeczność FreshRSS. Rozszerzenia znajdują się w osobnym repozytorium, a dokumentacja obejmuje użytkowników, administratorów i programistów.

Na co pozwala licencja AGPL-3.0

FreshRSS jest udostępniany na GNU Affero General Public License, wersja 3: jego manifest composer.json deklaruje ją jako AGPL-3.0, a README odsyła do tekstu licencji. Tekst ten potwierdza nieograniczone prawo do uruchamiania niezmodyfikowanego programu. Mogą więc Państwo używać obrazu opublikowanego przez projekt dla swojej firmy i zespołu, bez zakupu licencji.

Artykuł 13 dodaje warunek właściwy dla AGPL: jeśli Państwo zmodyfikują program, Państwa wersja musi oferować każdemu, kto korzysta z niej zdalnie, przez sieć, możliwość bezpłatnego uzyskania jej kodu źródłowego. Rozszerzenie zewnętrzne dodane do woluminu extensions podlega własnej licencji.

Instalacja przez Docker Compose

Projekt publikuje swoje oficjalne obrazy na Docker Hub, pod nazwą freshrss/freshrss, wraz z przykładowym plikiem Compose. Na serwerze z zainstalowanym Dockerem proszę utworzyć katalog o nazwie freshrss i umieścić w nim ten compose.yaml, zaczerpnięty z tego pliku i z README Dockera:

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

• Port opublikowany na 127.0.0.1: FreshRSS jest osiągalny wyłącznie przez odwrotne proxy, postawione na tym samym serwerze. Przykładowy plik projektu publikuje port 8080 do użytku lokalnego; adres 127.0.0.1 rezerwuje go tutaj dla proxy.
• Wolumin data przechowuje konfigurację, konta oraz, przy SQLite, bazę danych każdego użytkownika. README zaznacza, że zawiera on wszystkie dane osobowe. Docker Compose nadaje mu nazwę od katalogu: freshrss_data.
• Wolumin extensions przechowuje rozszerzenia zewnętrzne, jeśli je Państwo dodadzą.
• TZ przyjmuje strefę czasową serwera, w formacie PHP; domyślnie UTC.
• TRUSTED_PROXY zachowuje wartość z przykładowego pliku: prywatne zakresy, z których pochodzą żądania proxy. Od niej zależy, który adres trafia do dzienników, odwiedzającego czy proxy.
• Kontrola stanu uruchamia w regularnych odstępach cli/health.php, aby Docker wiedział, czy instancja odpowiada.

Tag latest, domyślny, podąża za ostatnią wersją numerowaną; edge podąża za wydaniem ciągłym; tag taki jak 1.30.4 przypina wersję, a przyrostek -alpine daje to samo na bazie Alpine zamiast Debiana. Sekcja o aktualizacjach wraca do tego wyboru.

Dokończenie instalacji

Gdy odwrotne proxy jest gotowe, proszę otworzyć swój adres HTTPS: kreator instalacji pyta o język, sprawdza serwer, proponuje wybór bazy danych, a następnie tworzy konto administratora, z hasłem i metodą logowania. SQLite działa bez żadnych przygotowań. Instalacja jest możliwa także z wiersza poleceń, przez cli/do-install.php i cli/create-user.php, uruchamiane przez docker exec --user www-data freshrss.

Jeśli chodzi o zasoby, README wymaga lekkiego serwera z Linuksem lub Windowsem i zaznacza, że FreshRSS działa nawet na Raspberry Pi 1, z czasem odpowiedzi poniżej sekundy, przy 150 kanałach i 22 000 artykułów. Rozmiar zależy od liczby użytkowników, kanałów i przechowywanych artykułów. Na Managed VPS wystarczy opisać nam swoje zastosowanie, a polecimy odpowiedni rozmiar.

HTTPS: odwrotne proxy

Do zastosowań produkcyjnych README Dockera zaleca odwrotne proxy na serwerze hosta, które zapewnia HTTPS. Najpierw proszę wybrać nazwę domeny lub subdomenę, taką jak rss.example.com, wskazującą na serwer rekordami A i AAAA. Projekt poleca Traefik i publikuje dla niego kompletny plik Compose, z certyfikatami Let’s Encrypt i przekierowaniem z HTTP na HTTPS; podaje też przykłady dla Apache, Nginx i Caddy.

Z Caddy

Caddy sam uzyskuje certyfikat i włącza HTTPS. Ten blok podąża za przykładem z dokumentacji dla subdomeny, skierowanym tutaj na port opublikowany lokalnie:

rss.example.com {
  reverse_proxy 127.0.0.1:8080
}

Z Nginx i Certbotem

Ten blok powtarza przykład Nginx z README Dockera dla katalogu głównego domeny, zredukowany do portu 80, aby Certbot mógł zainstalować HTTPS. Dwa ostatnie wiersze przekazują nagłówek Authorization, którego potrzebuje 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 następnie instaluje certyfikat i zajmuje się jego odnawianiem:

sudo certbot --nginx

Adres publiczny: base_url

FreshRSS przechowuje swój adres publiczny w base_url, w pliku data/config.php. Opierają się na nim API i WebSub: proszę sprawdzić, czy zawiera Państwa adres w https. README Dockera pokazuje, gdzie znaleźć ten plik w woluminie:

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/',

Odświeżanie kanałów: CRON_MIN

FreshRSS pobiera nowe artykuły skryptem app/actualize_script.php. Obraz Docker zawiera zadanie cykliczne, które uruchamia go w minutach podanych w CRON_MIN. Bez tej zmiennej albo przy pustej wartości zadanie pozostaje wyłączone, a kanały przestają się same odświeżać.

• Tempo: projekt zaleca mniej więcej dwa uruchomienia na godzinę, na przykład 13,43; */20 również się sprawdza.
• Limit: skrypt nie odświeża tego samego kanału częściej niż co dwadzieścia minut, więc gęstszy harmonogram nic nie daje.
• Czas rzeczywisty: przy zgodnych źródłach zadanie przejmuje WebSub. Wymaga on adresu publicznego, odczytywanego z base_url, a kreator instalacji włącza go, gdy serwer taki adres ma.

Inna opisana w dokumentacji metoda: zadanie cykliczne na serwerze hosta, które wywołuje skrypt wewnątrz kontenera. W takim przypadku proszę usunąć CRON_MIN z compose.yaml, aby zachować jedną metodę:

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

Od wersji 1.30.0 FreshRSS domyślnie odrzuca adresy sieci lokalnej, takie jak 127.0.0.1, aby chronić przed fałszowaniem żądań po stronie serwera. Sąsiednią usługę, która tworzy kanały, taką jak RSS-Bridge, dopuszcza się przez zmienną INTERNAL_HOST_ALLOWLIST, w postaci rss-bridge:80, albo w konfiguracji systemu. Wartość * usuwa wszelką kontrolę, a dokumentacja uznaje ją za niebezpieczną.

Konta i logowanie

Podczas instalacji FreshRSS proponuje logowanie formularzem, które wymaga JavaScriptu. To metoda domyślna i sprawdza się w większości instancji. Dokumentacja opisuje też inne:

Dokumentacja ostrzega, że FreshRSS ufa każdemu adresowi wymienionemu w TRUSTED_PROXY: słabo zabezpieczone proxy pozwoliłoby atakującemu ustawić nagłówek i uzyskać dostęp administratora. Tutaj port nasłuchuje wyłącznie na 127.0.0.1, co rezerwuje go dla proxy samego serwera. Dokumentacja odradza też jakąkolwiek instancję bez uwierzytelniania, gdy tylko serwer jest osiągalny spoza Państwa sieci.

Rejestracje i użytkownicy

• Domyślnie zamknięte: konfiguracja ustawia liczbę kont na 1, czyli konto administratora. Formularz rejestracji pojawia się tylko wtedy, gdy zwiększą Państwo tę liczbę w Administracja, Konfiguracja systemu; 0 usuwa wszelki limit.
• Konta tworzone przez administratora: Administracja, Zarządzanie użytkownikami, z językiem, nazwą użytkownika, hasłem i informacją, czy konto jest administratorem.
• Ponowne uwierzytelnienie jest wymagane przed działaniami wrażliwymi, takimi jak awansowanie użytkownika czy zastosowanie aktualizacji, domyślnie po 20 minutach.
• Weryfikacja adresów e-mail jest opcjonalna. Wymaga serwera SMTP, ustawianego przez mailer i smtp w data/config.php: dokumentacja podaje, że wysyłka przez funkcję PHP mail nie jest jeszcze obsługiwana w oficjalnych obrazach Docker.

Dla instancji współdzielonej przez kilka osób dokumentacja radzi otwierać konta osobom zaufanym i utrzymywać instancję za proxy lub zaporą, która blokuje dostęp do wewnętrznych zakresów adresów.

Aplikacje mobilne: API Google Reader i Fever

FreshRSS działa w przeglądarce, na dużych i małych ekranach, a także w aplikacjach na Androida, iOS, Linuksa, Windowsa i macOS. Aplikacje te korzystają z jednego z jego dwóch API: Google Reader, które README ocenia jako najlepsze, oraz Fever, o bardziej ograniczonych funkcjach, mniej wydajnego i mniej bezpiecznego.

1. Jako administrator proszę włączyć w sekcji Uwierzytelnianie opcję, która zezwala na dostęp przez API.
2. Każdy użytkownik ustawia w swoim profilu hasło API. Jest ono odrębne od hasła głównego, daje dostęp do mniejszej liczby rzeczy i jest przeznaczone do mniej bezpiecznych sytuacji.
3. W aplikacji proszę wpisać adres https://rss.example.com/api/greader.php, albo https://rss.example.com/api/fever.php dla Fever, wraz z nazwą użytkownika i tym hasłem API.

Do sprawdzenia służy link wyświetlany obok hasła API w profilu, który otwiera stronę testową: PASS przy pełnym teście potwierdza, że wszystko działa. Obraz Docker już ustawia Apache tak, by przyjmował zakodowane ukośniki, których potrzebują niektóre aplikacje; przy Nginx przed nim proszę zachować przekazywanie nagłówka Authorization.

README prowadzi tabelę zgodnych aplikacji, z ich platformą, API i funkcjami: między innymi Capy Reader i Readrops na Androidzie, FeedFlow na telefonie i komputerze, RSS Guard i NewsFlash na komputerze, ReadKit i Reeder Classic na iOS i macOS.

SQLite, PostgreSQL, MySQL czy MariaDB

FreshRSS ma wbudowaną obsługę SQLite, którą README Dockera opisuje jako najprostszą opcję, o dobrej wydajności. Strona wymagań zaleca PostgreSQL 10 lub nowszy, a przyjmuje też MariaDB 10.6 i MySQL 8.0 lub nowsze. Wyboru dokonuje się w kreatorze instalacji.

Dla PostgreSQL proszę dodać tę usługę do compose.yaml, zaczerpniętą z pliku docker-compose-db.yml projektu, a wolumin db do listy woluminów. Hasło trafia do pliku .env, obok 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'

W kreatorze proszę wybrać PostgreSQL i wpisać freshrss-db jako host, wraz z użytkownikiem, hasłem i bazą freshrss.

Do tego wyboru można wrócić później. Dokumentacja opisuje przejście z jednej bazy na inną, na przykład z MySQL na PostgreSQL, albo na nowszą wersję główną PostgreSQL: cli/db-backup.php kopiuje bazę każdego użytkownika do pliku SQLite, a następnie cli/db-restore.php wczytuje ją do nowej bazy.

Kopie zapasowe

README zaznacza, że FreshRSS jest dostarczany bez jakiejkolwiek gwarancji: to Państwa kopie zapasowe zachowują subskrypcje, artykuły i ustawienia. Oto, co dokumentacja prosi kopiować:

Woluminy, przy zatrzymanej usłudze

Dokumentacja uważa za bezpieczniejsze zatrzymanie usługi na czas prac konserwacyjnych. Woluminy Dockera kopiuje się za pomocą tymczasowego kontenera, metodą opisaną w dokumentacji Dockera:

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

Bazy danych, przy działającej usłudze

Od wersji 1.29.1 FreshRSS potrafi sam eksportować bazę każdego użytkownika do pliku SQLite, niezależnie od używanej bazy, i zachowywać tylko najnowsze eksporty. Ten eksport włącza się w data/config.php:

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

Następnie proszę zaplanować polecenie na serwerze, tutaj co noc. Każde uruchomienie zapisuje data/users/<user>/sqlite-backups/<date>.sqlite i usuwa pliki starsze niż siedem ostatnich:

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

Przy PostgreSQL proszę dodać zrzut własnym narzędziem bazy, jak w README Dockera. Opcja -T wyłącza terminal, który w zadaniu cyklicznym nie jest potrzebny:

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

Eksport OPML z interfejsu zachowuje listę kanałów, bez niektórych ustawień właściwych dla FreshRSS, takich jak dane logowania czy reguły pobierania ze stron. Pełną kopię zapewniają eksporty SQLite: umieszczone na dysku serwera, trafiają także do jego nocnych kopii zapasowych.

Przywracanie

1. Proszę zatrzymać FreshRSS poleceniem docker compose stop freshrss.
2. Proszę wczytać archiwum z powrotem do woluminów: docker run --rm --volumes-from freshrss -v "$PWD":/backup ubuntu tar -xzf /backup/freshrss-YYYY-MM-DD.tgz -C /var/www/FreshRSS.
3. Przy zewnętrznej bazie proszę przywrócić ją z jej zrzutu albo z plików SQLite poleceniem cli/db-restore.php --delete-backup --force-overwrite.
4. Proszę uruchomić ponownie poleceniem docker compose start freshrss, a następnie sprawdzić, czy kanały i artykuły są na miejscu.

Proszę powtarzać to ćwiczenie od czasu do czasu, na kopii: w ten sposób sprawdzają Państwo, że kopia zapasowa działa.

Aktualizacje

README Dockera podaje dwa polecenia, wydawane z katalogu z compose.yaml. Woluminy pozostają na miejscu:

docker compose pull
docker compose up -d

FreshRSS publikuje w dwóch kanałach. Wersje numerowane, tag latest, ukazują się kilka razy w roku, bez ustalonego kalendarza, a ich poprawki nie są przenoszone do starszych wersji. Wydanie ciągłe, tag edge, otrzymuje nowe funkcje i poprawki na bieżąco: od wersji 1.30.0 projekt zaleca je ze względu na szybsze poprawki bezpieczeństwa.

• Najpierw kopia zapasowa: dokumentacja prosi o kopię data/, rozszerzeń i bazy przed każdą aktualizacją.
• Wersja po wersji: jeśli mają Państwo kilka wersji zaległości, proszę przejść przez każdą z nich, na przykład z 1.26.0 do 1.27.1 przed 1.28.1, sprawdzając wszystko na każdym etapie. Przy Dockerze tagi takie jak 1.29.1 umożliwiają tę drogę.
• Ostatnie wydania: 1.30.4 z 21 października 2026 roku to czwarte wydanie bezpieczeństwa w serii 1.30. Poprawia podatności PHP w obrazach Alpine, po wersji 1.30.3, która przeniosła domyślny obraz Debian na Debiana 13.

Aby śledzić nowe wydania, projekt publikuje kanał Atom swoich wersji: wystarczy zasubskrybować go we własnej instancji FreshRSS.

Kto za co odpowiada na Managed VPS

Samodzielny hosting wymaga prowadzenia serwera, oprócz samej aplikacji. Na Managed VPS nasze zespoły przejmują serwer i proaktywnie czuwają nad Państwa instancją; FreshRSS pozostaje Państwa oprogramowaniem, z jego ustawieniami i danymi.

Jeśli wolą Państwo, aby nasze zespoły interweniowały w samej aplikacji, usługa ta jest rozliczana godzinowo lub ryczałtowo, z wyceną przekazaną przed interwencją.