first commit
This commit is contained in:
273
SETUP.md
Normal file
273
SETUP.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# Quick Setup Guide
|
||||
|
||||
Follow these steps to get News Agent running on your Fedora machine.
|
||||
|
||||
## 1. System Requirements
|
||||
|
||||
```bash
|
||||
# Update system
|
||||
sudo dnf update -y
|
||||
|
||||
# Install Python 3.11+
|
||||
sudo dnf install python3.11 python3-pip -y
|
||||
```
|
||||
|
||||
## 2. Install News Agent
|
||||
|
||||
```bash
|
||||
# Navigate to project directory
|
||||
cd ~/news-agent
|
||||
|
||||
# Create virtual environment
|
||||
python3.11 -m venv .venv
|
||||
|
||||
# Activate it
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install feedparser httpx openai pydantic pydantic-settings jinja2 premailer python-dotenv pyyaml aiosqlite
|
||||
```
|
||||
|
||||
## 3. Configuration
|
||||
|
||||
### Create `.env` file:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
nano .env
|
||||
```
|
||||
|
||||
Add your credentials:
|
||||
```env
|
||||
# OpenRouter API Key (required)
|
||||
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
|
||||
# SMTP Credentials (required)
|
||||
SMTP_USERNAME=your-email@yourdomain.com
|
||||
SMTP_PASSWORD=your-smtp-password
|
||||
|
||||
# Optional
|
||||
OPENROUTER_SITE_URL=https://yoursite.com
|
||||
OPENROUTER_SITE_NAME=YourSiteName
|
||||
```
|
||||
|
||||
Get OpenRouter API key from: https://openrouter.ai/keys
|
||||
|
||||
### Update `config.yaml`:
|
||||
```bash
|
||||
nano config.yaml
|
||||
```
|
||||
|
||||
Update email settings:
|
||||
```yaml
|
||||
email:
|
||||
to: "your-email@example.com" # Where to receive digest
|
||||
from: "news-agent@yourdomain.com" # Sender address
|
||||
smtp:
|
||||
host: "mail.yourdomain.com" # Your mail server
|
||||
port: 587 # 587 for STARTTLS, 465 for SSL
|
||||
use_tls: true # true for port 587
|
||||
use_ssl: false # true for port 465
|
||||
```
|
||||
|
||||
**Common mail servers:**
|
||||
- **Your own**: Use your mail server hostname and SMTP credentials
|
||||
- **Gmail**: `smtp.gmail.com:587` (requires App Password)
|
||||
- **Outlook**: `smtp.office365.com:587`
|
||||
|
||||
## 4. Test Run
|
||||
|
||||
```bash
|
||||
# Make sure virtual environment is activated
|
||||
source .venv/bin/activate
|
||||
|
||||
# Run the agent
|
||||
python -m src.main
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
INFO - News Agent starting...
|
||||
INFO - Database initialized
|
||||
INFO - Fetching from 15 RSS sources...
|
||||
INFO - Fetched 127 articles from all sources
|
||||
INFO - Saved 127 new articles
|
||||
INFO - Processing 127 new articles with AI...
|
||||
INFO - Filtering articles by relevance...
|
||||
INFO - Selected 15 relevant articles
|
||||
INFO - Generating AI summaries...
|
||||
INFO - Generating email digest...
|
||||
INFO - Sending email...
|
||||
INFO - Daily digest sent successfully with 15 articles!
|
||||
```
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
cat data/logs/news-agent.log
|
||||
```
|
||||
|
||||
## 5. Set Up Systemd Timer
|
||||
|
||||
```bash
|
||||
# Create user systemd directory
|
||||
mkdir -p ~/.config/systemd/user
|
||||
|
||||
# Update service file with correct paths
|
||||
sed "s|/home/%u/news-agent|$HOME/news-agent|g" systemd/news-agent.service > ~/.config/systemd/user/news-agent.service
|
||||
|
||||
# Copy timer file
|
||||
cp systemd/news-agent.timer ~/.config/systemd/user/
|
||||
|
||||
# Reload systemd
|
||||
systemctl --user daemon-reload
|
||||
|
||||
# Enable timer
|
||||
systemctl --user enable news-agent.timer
|
||||
systemctl --user start news-agent.timer
|
||||
|
||||
# Enable lingering (allows service to run when not logged in)
|
||||
sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
**Verify setup:**
|
||||
```bash
|
||||
# Check timer is active
|
||||
systemctl --user list-timers
|
||||
|
||||
# Should show:
|
||||
# NEXT LEFT LAST PASSED UNIT ACTIVATES
|
||||
# Tue 2024-01-27 07:00:00 CET 12h left - - news-agent.timer news-agent.service
|
||||
```
|
||||
|
||||
## 6. Monitoring
|
||||
|
||||
### View logs in real-time:
|
||||
```bash
|
||||
journalctl --user -u news-agent.service -f
|
||||
```
|
||||
|
||||
### Check last run:
|
||||
```bash
|
||||
systemctl --user status news-agent.service
|
||||
```
|
||||
|
||||
### Manual trigger:
|
||||
```bash
|
||||
systemctl --user start news-agent.service
|
||||
```
|
||||
|
||||
### View timer schedule:
|
||||
```bash
|
||||
systemctl --user list-timers news-agent.timer
|
||||
```
|
||||
|
||||
## 7. Verification Checklist
|
||||
|
||||
- [ ] Python 3.11+ installed
|
||||
- [ ] Virtual environment created and activated
|
||||
- [ ] All dependencies installed
|
||||
- [ ] `.env` file created with OpenRouter API key and SMTP credentials
|
||||
- [ ] `config.yaml` updated with your mail server settings
|
||||
- [ ] Test run completed successfully
|
||||
- [ ] Email received in inbox
|
||||
- [ ] Systemd timer enabled and scheduled
|
||||
- [ ] Lingering enabled for user
|
||||
|
||||
## Common Issues
|
||||
|
||||
### "No module named 'feedparser'"
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
pip install feedparser httpx openai pydantic pydantic-settings jinja2 premailer python-dotenv pyyaml aiosqlite
|
||||
```
|
||||
|
||||
### "Failed to send email"
|
||||
Check your SMTP credentials and server settings:
|
||||
```bash
|
||||
# Verify .env has SMTP credentials
|
||||
cat .env | grep SMTP
|
||||
|
||||
# Verify config.yaml has correct mail server
|
||||
grep -A 5 "smtp:" config.yaml
|
||||
|
||||
# Check logs for specific error
|
||||
tail -n 50 data/logs/news-agent.log
|
||||
```
|
||||
|
||||
Common issues:
|
||||
- Wrong port (587 for TLS, 465 for SSL)
|
||||
- Missing TLS/SSL setting
|
||||
- Invalid credentials
|
||||
- Firewall blocking SMTP port
|
||||
|
||||
### "API key not found"
|
||||
```bash
|
||||
# Verify .env file exists and has correct format
|
||||
cat .env
|
||||
|
||||
# Should show:
|
||||
# OPENROUTER_API_KEY=sk-or-v1-...
|
||||
```
|
||||
|
||||
### Timer not running
|
||||
```bash
|
||||
# Check timer status
|
||||
systemctl --user status news-agent.timer
|
||||
|
||||
# If inactive:
|
||||
systemctl --user enable news-agent.timer
|
||||
systemctl --user start news-agent.timer
|
||||
|
||||
# Enable lingering
|
||||
sudo loginctl enable-linger $USER
|
||||
```
|
||||
|
||||
## Customization
|
||||
|
||||
### Change schedule time
|
||||
Edit `~/.config/systemd/user/news-agent.timer`:
|
||||
```ini
|
||||
[Timer]
|
||||
OnCalendar=08:30 # Run at 8:30 AM instead
|
||||
```
|
||||
|
||||
Then reload:
|
||||
```bash
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user restart news-agent.timer
|
||||
```
|
||||
|
||||
### Add/remove RSS feeds
|
||||
Edit `config.yaml` under `sources.rss` section.
|
||||
|
||||
### Adjust AI filtering
|
||||
In `config.yaml`:
|
||||
```yaml
|
||||
ai:
|
||||
filtering:
|
||||
min_score: 7.0 # Stricter filtering (default: 6.5)
|
||||
max_articles: 10 # Fewer articles (default: 15)
|
||||
```
|
||||
|
||||
### Change AI model
|
||||
In `config.yaml`:
|
||||
```yaml
|
||||
ai:
|
||||
model: "anthropic/claude-3.5-haiku" # Better quality
|
||||
# or
|
||||
model: "meta-llama/llama-3.1-8b-instruct" # Cheaper
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Wait for first automated run** (tomorrow at 07:00)
|
||||
2. **Monitor costs** at https://openrouter.ai/activity
|
||||
3. **Adjust filtering threshold** based on article quality
|
||||
4. **Add custom RSS feeds** for your specific interests
|
||||
5. **Set up email forwarding** if not using local mailbox
|
||||
|
||||
## Support
|
||||
|
||||
- **Logs:** `data/logs/news-agent.log`
|
||||
- **Database:** `data/articles.db` (SQLite)
|
||||
- **Service status:** `systemctl --user status news-agent.service`
|
||||
- **OpenRouter Dashboard:** https://openrouter.ai/activity
|
||||
Reference in New Issue
Block a user