# FreshRSS Feed Reader

> Self-hosted RSS feed aggregator with web interface.

- Category: Productivity & Collaboration
- Difficulty: beginner
- Components: freshrss, postgresql
- Tags: rss, freshrss, feed-reader, news, aggregator
- Source: https://docker.recipes/productivity/freshrss-reader

## Overview

FreshRSS is a powerful, self-hosted RSS and Atom feed aggregator that allows users to stay updated with their favorite websites and blogs through a clean, web-based interface. Originally developed as an open-source alternative to Google Reader, FreshRSS provides advanced features like feed categorization, article filtering, full-text search, and keyboard shortcuts for efficient news consumption. Built with PHP and designed for privacy-conscious users, it keeps all your reading data under your control while offering a responsive design that works across desktop and mobile devices.

This deployment combines FreshRSS with a PostgreSQL database backend, creating a robust and scalable feed reading platform. The freshrss service runs the main application server with automated feed fetching via cron jobs, while the db service provides PostgreSQL 15 for reliable data storage of feeds, articles, and user preferences. The configuration includes persistent volumes for both application data and database storage, ensuring your feeds and reading history survive container updates.

This stack is ideal for individuals, families, or small teams who want to centralize their news consumption without relying on third-party services. The PostgreSQL backend makes it particularly suitable for users with large numbers of feeds or those who require advanced querying capabilities for article management. With support for OPML import/export and mobile app connectivity, this deployment serves as a complete replacement for commercial feed readers while maintaining full data ownership.

## Features

- Advanced feed management with categories, tags, and automatic duplicate detection
- Full-text search across all articles with PostgreSQL's powerful indexing capabilities
- Automated feed refreshing with configurable cron schedule (1,31 minutes by default)
- OPML import/export for easy migration from other feed readers like Google Reader or Feedly
- Multi-user support with individual reading preferences and feed subscriptions
- API access for integration with mobile apps like EasyRSS or FeedMe
- Article filtering and labeling system for organizing content by keywords or sources
- Keyboard shortcuts and reading view customization for power users

## Use cases

- Personal news aggregation for staying updated with tech blogs, news sites, and industry publications
- Small team knowledge sharing by subscribing to relevant industry feeds and sharing articles
- Research workflow management for academics tracking multiple journal RSS feeds and publication updates
- Content curation for bloggers and writers who need to monitor competitor and inspiration sources
- Privacy-focused news consumption for users wanting to avoid tracking by commercial feed readers
- Family news hub for sharing and organizing feeds from local news, school updates, and hobby sites
- Developer productivity tool for following GitHub releases, documentation updates, and programming blogs

## Prerequisites

- Docker and Docker Compose installed on the host system
- Minimum 512MB RAM available (1GB recommended for PostgreSQL performance)
- Port 8080 available for the FreshRSS web interface
- Database password configured in environment variables or .env file
- At least 2GB free disk space for application data and article storage
- Basic understanding of RSS/Atom feeds and OPML format for feed management

## docker-compose.yml

```yaml
services:
  freshrss:
    image: freshrss/freshrss:latest
    container_name: freshrss
    environment:
      - TZ=UTC
      - CRON_MIN=1,31
    volumes:
      - freshrss-data:/var/www/FreshRSS/data
      - freshrss-extensions:/var/www/FreshRSS/extensions
    ports:
      - "8080:80"
    depends_on:
      - db
    networks:
      - freshrss-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: freshrss-db
    environment:
      - POSTGRES_USER=freshrss
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=freshrss
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - freshrss-network
    restart: unless-stopped

volumes:
  freshrss-data:
  freshrss-extensions:
  postgres-data:

networks:
  freshrss-network:
    driver: bridge
```

## .env

```bash
# FreshRSS
DB_PASSWORD=secure_freshrss_password
```

## Usage notes

- Web UI at http://localhost:8080
- Complete setup wizard
- Import OPML feeds
- Mobile apps available
- API for external clients

## Troubleshooting

- Database connection failed during setup: Ensure DB_PASSWORD environment variable is set and matches between freshrss and db services
- Feeds not updating automatically: Check that CRON_MIN environment variable is properly configured and container has sufficient resources
- PostgreSQL container fails to start: Verify postgres-data volume permissions and ensure no other PostgreSQL instances are using default ports
- FreshRSS interface shows database errors: Wait for PostgreSQL to fully initialize before accessing the web UI, or restart the freshrss container
- Cannot import OPML file: Ensure the OPML file is valid XML and doesn't exceed PHP upload limits in the FreshRSS configuration
- Mobile app cannot connect to API: Verify that API access is enabled in FreshRSS settings and authentication tokens are properly configured

