Fedi Feed Router (FFR) v1.0.0

A minimal working version — limited to two hardcoded sources, designed for self-hosters.
Future versions will expand configurability and support.

---

🔰 Project Overview

One-liner: FFR routes content from RSS/Atom feeds to the fediverse based on keyword matching.

FFR is a self-hosted tool that monitors RSS/Atom feeds, filters articles based on keywords, and automatically publishes matching content to fediverse platforms like Lemmy. This v1.0.0 release provides a working foundation with two hardcoded news sources (CBC and BBC), designed specifically for self-hosters who want a simple, privacy-first solution without SaaS dependencies.

⚙️ Features

Current v1.0.0 features:

• ✅ Fetches articles from two hardcoded RSS feeds (CBC News, BBC News)
• ✅ Keyword-based content filtering and matching
• ✅ Automatic posting to Lemmy communities
• ✅ Web dashboard for monitoring and management
• ✅ Docker-based deployment for easy self-hosting
• ✅ Privacy-first design with no external dependencies

Limitations (to be addressed in future versions):

• Feed sources are currently hardcoded (not user-configurable)
• Only supports Lemmy as target platform
• Basic keyword matching (no regex or complex rules yet)

🚀 Installation

Quick Start with Docker

1. Clone the repository:

   git clone https://codeberg.org/lvl0/ffr.git
   cd ffr
   

2. Create environment file:

   cp docker/production/.env.example .env
   

3. Configure your environment variables:

   # Required variables only
   APP_URL=http://your-domain.com:8000
   DB_PASSWORD=your-secure-db-password
   DB_ROOT_PASSWORD=your-secure-root-password
   

4. Start the application:

   docker-compose -f docker/production/docker-compose.yml up -d
   

The application will be available at http://localhost:8000

System Requirements

• Docker and Docker Compose (or Podman)
• 2GB RAM minimum
• 10GB disk space
• Linux/macOS/Windows with WSL2

🕹️ Usage

Web Interface

Access the dashboard at http://localhost:8000 to:

• View fetched articles
• Monitor posting queue
• Check system logs
• Manage keywords (coming in v2.0)

Manual Commands

Trigger article refresh manually:

docker compose exec app php artisan article:refresh

View application logs:

docker compose logs -f app

Scheduled Tasks

The application automatically:

• Fetches new articles every hour
• Publishes matching articles every 5 minutes
• Syncs with Lemmy communities every 10 minutes

📜 Logging & Debugging

Log locations:

• Application logs: Available in web dashboard under "Logs" section
• Docker logs: docker compose logs -f app
• Laravel logs: Inside container at /var/www/html/backend/storage/logs/

Debug mode: To enable debug mode for troubleshooting, add to your .env:

APP_DEBUG=true

⚠️ Remember to disable debug mode in production!

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Report bugs: Open an issue describing the problem
2. Suggest features: Create an issue with your idea
3. Submit PRs: Fork, create a feature branch, and submit a pull request
4. Improve docs: Documentation improvements are always appreciated

For development setup, see the Development Setup section below.

📘 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).
See LICENSE file for details.

🧭 Roadmap

v1.0.0 (Current Release)

• ✅ Basic feed fetching from hardcoded sources
• ✅ Keyword filtering
• ✅ Lemmy posting
• ✅ Web dashboard
• ✅ Docker deployment

v2.0.0 (Planned)

• User-configurable feed sources
• Advanced filtering rules (regex, boolean logic)
• Support for Mastodon and other ActivityPub platforms
• API for external integrations
• Multi-user support with permissions

v3.0.0 (Future)

• Machine learning-based content categorization
• Feed discovery and recommendations
• Scheduled posting with optimal timing
• Analytics and insights dashboard

---

Development Setup

For contributors and developers who want to work on FFR:

Prerequisites

• Podman and podman-compose (or Docker)
• Git
• PHP 8.2+ (for local development)
• Node.js 18+ (for frontend development)

Quick Start

1. Clone and start the development environment:

   git clone https://codeberg.org/lvl0/ffr.git
   cd ffr
   ./docker/dev/podman/start-dev.sh
   

2. Access the development environment:

   • Web interface: http://localhost:8000
   • Vite dev server: http://localhost:5173
   • Database: localhost:3307
   • Redis: localhost:6380

Development Commands

# Run tests with coverage
podman-compose -f docker/dev/podman/docker-compose.yml exec app bash -c "cd backend && XDEBUG_MODE=coverage php artisan test --coverage-html=coverage-report"

# Execute artisan commands
podman-compose -f docker/dev/podman/docker-compose.yml exec app php artisan migrate
podman-compose -f docker/dev/podman/docker-compose.yml exec app php artisan tinker

# View logs
podman-compose -f docker/dev/podman/docker-compose.yml logs -f

# Access container shell
podman-compose -f docker/dev/podman/docker-compose.yml exec app bash

# Stop environment
podman-compose -f docker/dev/podman/docker-compose.yml down

Development Features

• Hot reload: Vite automatically reloads frontend changes
• Pre-seeded database: Sample data for immediate testing
• Laravel Horizon: Queue monitoring dashboard
• Xdebug: Configured for debugging and code coverage
• Redis: For caching, sessions, and queues

---

Support

For help and support:

• 💬 Open a Discussion
• 🐛 Report Issues

---

Built with ❤️ for the self-hosting community