Update for v1.0.0

2025-08-15 10:32:28 +02:00 · 2025-08-15 10:32:28 +02:00 · cd830dfbc1
commit cd830dfbc1
parent 3c3116ae55
1 changed files with 156 additions and 142 deletions
--- a/README.md
+++ b/README.md
@ -1,205 +1,219 @@
-# Fedi Feed Router
+# 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>

-`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 <repository-url>
+   git clone https://codeberg.org/lvl0/ffr.git
   cd ffr
   ./docker/dev/podman/start-dev.sh
   ```

-2. **Access the application:**
-   - **Web interface**: http://localhost:8000
-   - **Vite dev server**: http://localhost:5173  
-   - **Database**: localhost:3307
-   - **Redis**: localhost:6380
+2. **Access the development environment:**
+   - Web interface: http://localhost:8000
+   - Vite dev server: http://localhost:5173
+   - Database: localhost:3307
+   - Redis: localhost:6380

 ### Development Commands

-**Load Sail-compatible aliases:**
 ```bash
-source docker/dev/podman/podman-sail-alias.sh
-```
-
-**Useful commands:**
-```bash
-# Run tests
-ffr-test
+# 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
-ffr-artisan migrate
-ffr-artisan tinker
+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 application logs
-ffr-logs
+# View logs
+podman-compose -f docker/dev/podman/docker-compose.yml logs -f

-# Open container shell
-ffr-shell
+# 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
 ```

-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

- **Hot reload**: Vite automatically reloads frontend changes
- **Database**: Pre-configured MySQL with migrations and seeders
- **Redis**: Configured for caching, sessions, and queues
- **Laravel Horizon**: Available for queue monitoring
- **No configuration needed**: Development environment uses preset configuration
+- **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>