219 lines
No EOL
6 KiB
Markdown
219 lines
No EOL
6 KiB
Markdown
# Fedi Feed Router (FFR) v1.0.0
|
|
|
|
<div align="center">
|
|
<img src="backend/public/images/ffr-logo-600.png" alt="FFR Logo" width="200">
|
|
|
|
**A minimal working version — limited to two hardcoded sources, designed for self-hosters.**
|
|
*Future versions will expand configurability and support.*
|
|
</div>
|
|
|
|
---
|
|
|
|
## 🔰 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:**
|
|
```bash
|
|
git clone https://codeberg.org/lvl0/ffr.git
|
|
cd ffr
|
|
```
|
|
|
|
2. **Create environment file:**
|
|
```bash
|
|
cp docker/production/.env.example .env
|
|
```
|
|
|
|
3. **Configure your environment variables:**
|
|
```env
|
|
# 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:**
|
|
```bash
|
|
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:
|
|
```bash
|
|
docker compose exec app php artisan article:refresh
|
|
```
|
|
|
|
View application logs:
|
|
```bash
|
|
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`:
|
|
```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](#development-setup) section below.
|
|
|
|
## 📘 License
|
|
|
|
This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).
|
|
See [LICENSE](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:**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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](https://codeberg.org/lvl0/ffr/discussions)
|
|
- 🐛 Report [Issues](https://codeberg.org/lvl0/ffr/issues)
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
Built with ❤️ for the self-hosting community
|
|
</div> |