+
+**A minimal working version â limited to two hardcoded sources, designed for self-hosters.**
+*Future versions will expand configurability and support.*
-`ffr` is a self-hosted tool for routing content from RSS/Atom feeds to the fediverse.
+---
-It watches feeds, matches entries based on keywords or rules, and publishes them to platforms like Lemmy, Mastodon, or anything ActivityPub-compatible.
+## đ° Project Overview
-## Features
+**One-liner:** FFR routes content from RSS/Atom feeds to the fediverse based on keyword matching.
-- Keyword-based routing from any RSS/Atom feed
-- Publish to Lemmy, Mastodon, or other fediverse services
-- YAML or JSON route configs
-- CLI and/or daemon mode
-- Self-hosted, privacy-first, no SaaS dependencies
+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
-## Docker Deployment
+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
-### Building the Image
+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 build -t your-registry/lemmy-poster:latest .
-docker push your-registry/lemmy-poster:latest
+docker compose exec app php artisan article:refresh
```
-### Docker Compose
-
-Create a `docker-compose.yml` file:
-
-```yaml
-services:
- app-web:
- image: your-registry/lemmy-poster:latest
- command: ["web"]
- ports:
- - "8000:8000"
- environment:
- - DB_DATABASE=${DB_DATABASE}
- - DB_USERNAME=${DB_USERNAME}
- - DB_PASSWORD=${DB_PASSWORD}
- - LEMMY_INSTANCE=${LEMMY_INSTANCE}
- - LEMMY_USERNAME=${LEMMY_USERNAME}
- - LEMMY_PASSWORD=${LEMMY_PASSWORD}
- - LEMMY_COMMUNITY=${LEMMY_COMMUNITY}
- depends_on:
- - mysql
- volumes:
- - storage_data:/var/www/html/storage/app
- restart: unless-stopped
-
- app-queue:
- image: your-registry/lemmy-poster:latest
- command: ["queue"]
- environment:
- - DB_DATABASE=${DB_DATABASE}
- - DB_USERNAME=${DB_USERNAME}
- - DB_PASSWORD=${DB_PASSWORD}
- - LEMMY_INSTANCE=${LEMMY_INSTANCE}
- - LEMMY_USERNAME=${LEMMY_USERNAME}
- - LEMMY_PASSWORD=${LEMMY_PASSWORD}
- - LEMMY_COMMUNITY=${LEMMY_COMMUNITY}
- depends_on:
- - mysql
- volumes:
- - storage_data:/var/www/html/storage/app
- restart: unless-stopped
-
- mysql:
- image: mysql:8.0
- command: --host-cache-size=0 --innodb-use-native-aio=0 --sql-mode=STRICT_TRANS_TABLES,NO_ZERO_DATE,NO_ZERO_IN_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION --log-error-verbosity=1
- environment:
- - MYSQL_DATABASE=${DB_DATABASE}
- - MYSQL_USER=${DB_USERNAME}
- - MYSQL_PASSWORD=${DB_PASSWORD}
- - MYSQL_ROOT_PASSWORD=${DB_PASSWORD}
- - TZ=UTC
- volumes:
- - mysql_data:/var/lib/mysql
- restart: unless-stopped
-
-volumes:
- mysql_data:
- storage_data:
+View application logs:
+```bash
+docker compose logs -f app
```
-### Environment Variables
+### Scheduled Tasks
-Create a `.env` file with:
+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
-# Database Settings
-DB_DATABASE=lemmy_poster
-DB_USERNAME=lemmy_user
-DB_PASSWORD=your-password
-
-# Lemmy Settings
-LEMMY_INSTANCE=your-lemmy-instance.com
-LEMMY_USERNAME=your-lemmy-username
-LEMMY_PASSWORD=your-lemmy-password
-LEMMY_COMMUNITY=your-target-community
+APP_DEBUG=true
```
+â ī¸ Remember to disable debug mode in production!
-### Deployment
+## đ¤ Contributing
-1. Build and push the image to your registry
-2. Copy the docker-compose.yml to your server
-3. Create the .env file with your environment variables
-4. Run: `docker compose up -d`
+We welcome contributions! Here's how you can help:
-The application will automatically:
-- Wait for the database to be ready
-- Run database migrations on first startup
-- Start the queue worker after migrations complete
-- Handle race conditions between web and queue containers
+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
-### Initial Setup
+For development setup, see the [Development Setup](#development-setup) section below.
-After deployment, the article refresh will run every hour. To trigger the initial article fetch manually:
+## đ License
-```bash
-docker compose exec app-web php artisan article:refresh
-```
+This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).
+See [LICENSE](LICENSE) file for details.
-The application will then automatically:
-- Fetch new articles every hour
-- Publish valid articles every 5 minutes
-- Sync community posts every 10 minutes
+## đ§ Roadmap
-The web interface will be available on port 8000.
+### v1.0.0 (Current Release)
+- â
Basic feed fetching from hardcoded sources
+- â
Keyword filtering
+- â
Lemmy posting
+- â
Web dashboard
+- â
Docker deployment
-### Architecture
+### 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
-The application uses a multi-container setup:
-- **app-web**: Serves the Laravel web interface and handles HTTP requests
-- **app-queue**: Processes background jobs (article fetching, Lemmy posting)
-- **mysql**: Database storage for articles, logs, and application data
+### v3.0.0 (Future)
+- [ ] Machine learning-based content categorization
+- [ ] Feed discovery and recommendations
+- [ ] Scheduled posting with optimal timing
+- [ ] Analytics and insights dashboard
-Both app containers use the same Docker image but with different commands (`web` or `queue`). Environment variables are passed from your `.env` file to configure database access and Lemmy integration.
+---
## Development Setup
-For local development with Podman:
+For contributors and developers who want to work on FFR:
### Prerequisites
-- Podman and podman-compose installed
+- 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