lvl0/fedi-feed-router
1
0
Fork 0
Code Issues 15 Pull requests Projects Releases 2 Packages Wiki Activity Actions

Update for v1.0.0

Browse source
This commit is contained in:
myrmidex 2025-08-15 10:32:28 +02:00
parent 3c3116ae55
commit cd830dfbc1
1 changed files with 156 additions and 142 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

298
README.md
View file

@ -1,205 +1,219 @@
# Fedi Feed Router # Fedi Feed Router (FFR) v1.0.0
<div align="center"> <div align="center">
<img src="backend/public/images/ffr-logo-600.png" alt="FFR Logo" width="200"> <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> </div>
`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 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.
- 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
## ⚙️ 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 ```bash
docker build -t your-registry/lemmy-poster:latest . docker compose exec app php artisan article:refresh
docker push your-registry/lemmy-poster:latest
``` ```
### Docker Compose View application logs:
```bash
Create a `docker-compose.yml` file: docker compose logs -f app
```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:
``` ```
### 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 ```env
# Database Settings APP_DEBUG=true
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
``` ```
⚠️ Remember to disable debug mode in production!
### Deployment ## 🤝 Contributing
1. Build and push the image to your registry We welcome contributions! Here's how you can help:
2. Copy the docker-compose.yml to your server
3. Create the .env file with your environment variables
4. Run: `docker compose up -d`
The application will automatically: 1. **Report bugs:** Open an issue describing the problem
- Wait for the database to be ready 2. **Suggest features:** Create an issue with your idea
- Run database migrations on first startup 3. **Submit PRs:** Fork, create a feature branch, and submit a pull request
- Start the queue worker after migrations complete 4. **Improve docs:** Documentation improvements are always appreciated
- Handle race conditions between web and queue containers
### 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 This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).
docker compose exec app-web php artisan article:refresh See [LICENSE](LICENSE) file for details.
```
The application will then automatically: ## 🧭 Roadmap
- Fetch new articles every hour
- Publish valid articles every 5 minutes
- Sync community posts every 10 minutes
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: ### v3.0.0 (Future)
- **app-web**: Serves the Laravel web interface and handles HTTP requests - [ ] Machine learning-based content categorization
- **app-queue**: Processes background jobs (article fetching, Lemmy posting) - [ ] Feed discovery and recommendations
- **mysql**: Database storage for articles, logs, and application data - [ ] 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 ## Development Setup
For local development with Podman: For contributors and developers who want to work on FFR:
### Prerequisites ### Prerequisites
- Podman and podman-compose installed - Podman and podman-compose (or Docker)
- Git - Git
- PHP 8.2+ (for local development)
- Node.js 18+ (for frontend development)
### Quick Start ### Quick Start
1. **Clone and start the development environment:** 1. **Clone and start the development environment:**
```bash ```bash
git clone <repository-url> git clone https://codeberg.org/lvl0/ffr.git
cd ffr cd ffr
./docker/dev/podman/start-dev.sh ./docker/dev/podman/start-dev.sh
``` ```
2. **Access the application:** 2. **Access the development environment:**
- **Web interface**: http://localhost:8000 - Web interface: http://localhost:8000
- **Vite dev server**: http://localhost:5173 - Vite dev server: http://localhost:5173
- **Database**: localhost:3307 - Database: localhost:3307
- **Redis**: localhost:6380 - Redis: localhost:6380
### Development Commands ### Development Commands
**Load Sail-compatible aliases:**
```bash ```bash
source docker/dev/podman/podman-sail-alias.sh # 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"
**Useful commands:**
```bash
# Run tests
ffr-test
# Execute artisan commands # Execute artisan commands
ffr-artisan migrate podman-compose -f docker/dev/podman/docker-compose.yml exec app php artisan migrate
ffr-artisan tinker podman-compose -f docker/dev/podman/docker-compose.yml exec app php artisan tinker
# View application logs # View logs
ffr-logs podman-compose -f docker/dev/podman/docker-compose.yml logs -f
# Open container shell # Access container shell
ffr-shell podman-compose -f docker/dev/podman/docker-compose.yml exec app bash
# Stop environment # Stop environment
podman-compose -f docker/dev/podman/docker-compose.yml down podman-compose -f docker/dev/podman/docker-compose.yml down
``` ```
Run tests:
```sh
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"
```
### Development Features ### Development Features
- **Hot reload**: Vite automatically reloads frontend changes - **Hot reload:** Vite automatically reloads frontend changes
- **Database**: Pre-configured MySQL with migrations and seeders - **Pre-seeded database:** Sample data for immediate testing
- **Redis**: Configured for caching, sessions, and queues - **Laravel Horizon:** Queue monitoring dashboard
- **Laravel Horizon**: Available for queue monitoring - **Xdebug:** Configured for debugging and code coverage
- **No configuration needed**: Development environment uses preset configuration - **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>