vikingowl/owly-news
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[update] overhauled README.md to reflect new Rust backend, modernized tooling instructions, updated frontend and backend setup guides, and improved clarity on application structure

Browse Source
This commit is contained in:
vikingowl
2025-08-06 12:28:08 +02:00
parent 7b114a6145
commit 0f1632ad65
1 changed files with 68 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
README.md
View File

@@ -1,6 +1,6 @@
# Owly News Summariser
Owly News Summariser is a web application that fetches news articles from various RSS feeds, uses an LLM (Large Language Model) to summarize them, and presents them in a clean, user-friendly interface.
Owly News Summariser is a modern web application that fetches news articles from various RSS feeds, uses an LLM (Large Language Model) to summarize them, and presents them in a clean, user-friendly interface.
## Features
@@ -9,97 +9,56 @@ Owly News Summariser is a web application that fetches news articles from variou
- Filters news by country
- Progressive Web App (PWA) support for offline access
- Scheduled background updates
- High-performance Rust backend for optimal resource usage
- Modern Vue.js frontend with TypeScript support
## Project Structure
The project consists of two main components:
The project consists of multiple components:
- **Backend**: A FastAPI application that fetches and processes news feeds, summarizes articles, and provides API endpoints
- **Frontend**: A Vue.js application that displays the news and provides a user interface for managing feeds
- **Backend (Rust)**: Primary backend written in Rust using Axum framework for high performance (`backend-rust/`)
- **Backend (Python)**: Legacy FastAPI backend (`backend/`)
- **Frontend**: Modern Vue.js 3 application with TypeScript and Tailwind CSS (`frontend/`)
## Prerequisites
- Python 3.8+ for the backend
- Node.js 16+ and Yarn for the frontend
### For Rust Backend (Recommended)
- Rust 1.88.0+
- [Ollama](https://ollama.ai/) for article summarization
- SQLite (handled automatically by SQLx)
### For Python Backend (Legacy)
- Python 3.8+
- [Ollama](https://ollama.ai/) for article summarization
## Installing Yarn
Yarn is a package manager for JavaScript that's required for the frontend. Here's how to install it:
### Using npm (recommended)
If you already have Node.js installed, the easiest way to install Yarn is via npm:
```bash
npm install -g yarn
```
### Platform-specific installations
#### Windows
- **Using Chocolatey**: `choco install yarn`
- **Using Scoop**: `scoop install yarn`
- **Manual installation**: Download and run the [installer](https://classic.yarnpkg.com/latest.msi)
#### macOS
- **Using Homebrew**: `brew install yarn`
- **Using MacPorts**: `sudo port install yarn`
#### Linux
- **Debian/Ubuntu**:
```bash
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn
```
- **CentOS/Fedora/RHEL**:
```bash
curl --silent --location https://dl.yarnpkg.com/rpm/yarn.repo | sudo tee /etc/yum.repos.d/yarn.repo
sudo yum install yarn
```
- **Arch Linux**: `pacman -S yarn`
After installation, verify Yarn is installed correctly:
```bash
yarn --version
```
### For Frontend
- Node.js 22+ and npm
- Modern web browser with PWA support
## Setup
### Backend Setup
### Rust Backend Setup (Recommended)
1. Navigate to the backend directory:
1. Navigate to the Rust backend directory:
```bash
cd backend
cd backend-rust
```
2. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. Create a `.env` file based on the example:
2. Create a `.env` file based on the example:
```bash
cp example.env .env
```
5. Customize the `.env` file as needed:
- `OLLAMA_HOST`: URL for the Ollama service (default: http://localhost:11434)
- `CRON_HOURS`: Interval for scheduled news fetching (default: 1)
3. Customize the `.env` file as needed:
- `DATABASE_URL`: SQLite database connection string
- `OLLAMA_BASE_URL`: URL for the Ollama service (default: http://localhost:11434)
- Other configuration options as documented in the example file
4. Run database migrations:
```bash
cargo install sqlx-cli
sqlx migrate run
```
### Frontend Setup
@@ -110,29 +69,24 @@ yarn --version
2. Install dependencies:
```bash
yarn
npm install
```
## Running the Application
### Running the Backend
### Running the Rust Backend
1. Navigate to the backend directory:
1. Navigate to the Rust backend directory:
```bash
cd backend
cd backend-rust
```
2. Activate the virtual environment:
2. Start the backend server:
```bash
source venv/bin/activate # On Windows: venv\Scripts\activate
cargo run
```
3. Start the backend server:
```bash
uvicorn app.main:app --reload
```
The backend will be available at http://localhost:8000
The backend will be available at http://localhost:3000
### Running the Frontend
@@ -143,21 +97,26 @@ yarn --version
2. Start the development server:
```bash
yarn dev:watch
npm run dev
```
The frontend will be available at http://localhost:5173
## Building for Production
### Building the Backend
### Building the Rust Backend
The backend can be deployed as a standard FastAPI application. You can use tools like Gunicorn with Uvicorn workers:
1. Navigate to the Rust backend directory:
```bash
cd backend-rust
```
```bash
pip install gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker
```
2. Build the optimized release binary:
```bash
cargo build --release
```
The binary will be available at `target/release/owly-news-summariser`
### Building the Frontend
@@ -168,32 +127,32 @@ gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker
2. Build the frontend:
```bash
yarn build
npm run build
```
The built files will be in the `dist` directory and can be served by any static file server.
## API Endpoints
## Development
The backend provides the following API endpoints:
### Code Quality
- `GET /news`: Get news articles with optional filtering
- `GET /meta/last_sync`: Get the timestamp of the last feed synchronization
- `POST /meta/cron`: Set the schedule for automatic feed synchronization
- `GET /meta/feeds`: List all configured feeds
- `POST /meta/feeds`: Add a new feed
- `DELETE /meta/feeds`: Delete a feed
- `GET /meta/model`: Check the status of the LLM model
- `POST /meta/sync`: Manually trigger a feed synchronization
The project includes comprehensive tooling for code quality:
## Environment Variables
**Frontend:**
- ESLint with Vue and TypeScript support
- Prettier for code formatting
- Vitest for testing
- TypeScript for type safety
- Oxlint for additional linting
### Backend
**Backend (Rust):**
- Standard Rust tooling (`cargo fmt`, `cargo clippy`)
- SQLx for compile-time checked SQL queries
- `OLLAMA_HOST`: URL for the Ollama service
- `CRON_HOURS`: Interval for scheduled news fetching in hours
- `DATABASE_URL`: SQLite database connection string
### Testing
## License
Code ist unter der [PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/) lizenziert. Für jegliche kommerzielle Nutzung bitte Kontakt aufnehmen.
Run frontend tests:
```bash
cd frontend
npm run test
```