first commit

2026-01-26 12:34:00 +01:00
commit e64465a7e6
29 changed files with 2952 additions and 0 deletions
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -0,0 +1,217 @@
+# Changes for External Mail Server Support
+
+This document summarizes the changes made to support external mail servers instead of local Postfix.
+
+## Files Modified
+
+### 1. `config.yaml`
+- Updated SMTP section to use external mail server settings
+- Changed default port from 25 to 587 (standard STARTTLS port)
+- Enabled TLS by default
+- Added comments explaining port and encryption options
+
+**Before:**
+```yaml
+smtp:
+  host: "localhost"
+  port: 25
+  use_tls: false
+  use_ssl: false
+```
+
+**After:**
+```yaml
+smtp:
+  host: "mail.yourdomain.com"
+  port: 587  # Standard SMTP submission port (use 465 for SSL)
+  use_tls: true  # Use STARTTLS (for port 587)
+  use_ssl: false  # Set to true if using port 465
+  # Username and password are loaded from .env file for security
+```
+
+### 2. `.env.example`
+- Added SMTP_USERNAME field
+- Added SMTP_PASSWORD field
+- Added documentation for SMTP credentials
+
+**Added:**
+```env
+# SMTP Credentials for your mail server
+SMTP_USERNAME=your-email@yourdomain.com
+SMTP_PASSWORD=your-smtp-password
+```
+
+### 3. `src/config.py`
+- Added `smtp_username` field to `EnvSettings` class
+- Added `smtp_password` field to `EnvSettings` class
+- Modified `Config.email` property to merge SMTP credentials from environment variables into email configuration
+
+**Changes:**
+- Environment variables now include SMTP credentials
+- SMTP credentials are automatically loaded from `.env` and merged into config
+- Keeps passwords secure (not in config.yaml)
+
+### 4. `README.md`
+- Removed Postfix installation instructions
+- Updated prerequisites to mention "SMTP Server" instead of Postfix
+- Added SMTP configuration examples for various providers
+- Updated configuration steps to include SMTP credentials
+- Renumbered installation steps (removed Postfix step)
+
+### 5. `SETUP.md`
+- Removed Postfix installation and configuration sections
+- Updated system requirements (no Postfix needed)
+- Added SMTP credentials to `.env` configuration
+- Updated email configuration section with SMTP examples
+- Updated verification checklist
+- Updated troubleshooting section for SMTP issues
+
+## New Files Added
+
+### 6. `SMTP_CONFIG.md`
+Comprehensive guide for configuring SMTP with:
+- Step-by-step setup instructions
+- Common mail server configurations (Gmail, Outlook, SendGrid, etc.)
+- Port and encryption guide (587 vs 465 vs 25)
+- Testing procedures
+- Troubleshooting common SMTP errors
+- Security best practices
+- Example working configurations
+
+## How It Works
+
+### Configuration Flow
+
+1. **User creates `.env` file** with SMTP credentials:
+   ```env
+   SMTP_USERNAME=user@domain.com
+   SMTP_PASSWORD=password
+   ```
+
+2. **User edits `config.yaml`** with mail server settings:
+   ```yaml
+   smtp:
+     host: "mail.domain.com"
+     port: 587
+     use_tls: true
+   ```
+
+3. **Application loads configuration**:
+   - `EnvSettings` loads SMTP credentials from `.env`
+   - `Config` loads mail server settings from `config.yaml`
+   - `Config.email` property merges them together
+
+4. **Email sender uses merged configuration**:
+   - `EmailSender` receives complete SMTP config
+   - Connects to external mail server
+   - Authenticates with username/password
+   - Sends email via authenticated SMTP
+
+### Security Benefits
+
+- **Credentials separated from code**: SMTP passwords in `.env` (gitignored)
+- **Mail server settings in config**: Non-sensitive info in `config.yaml`
+- **No local mail server needed**: Simpler setup, fewer services to maintain
+- **Industry standard**: Works with any SMTP provider
+
+## What Users Need to Do
+
+### Required Changes
+
+1. **Update `.env` file**:
+   ```bash
+   cp .env.example .env
+   nano .env
+   ```
+   Add:
+   ```env
+   SMTP_USERNAME=your-email@domain.com
+   SMTP_PASSWORD=your-password
+   ```
+
+2. **Update `config.yaml`**:
+   ```bash
+   nano config.yaml
+   ```
+   Change email section:
+   ```yaml
+   email:
+     to: "recipient@example.com"
+     from: "sender@domain.com"
+     smtp:
+       host: "mail.domain.com"
+       port: 587
+       use_tls: true
+       use_ssl: false
+   ```
+
+### No Longer Needed
+
+- Postfix installation
+- Postfix configuration
+- Local mail server maintenance
+- Mail relay setup
+
+## Testing
+
+To test the new configuration:
+
+```bash
+# 1. Set up credentials
+cp .env.example .env
+nano .env  # Add SMTP credentials
+
+# 2. Configure mail server
+nano config.yaml  # Update SMTP settings
+
+# 3. Test run
+source .venv/bin/activate
+python -m src.main
+
+# 4. Check logs
+tail -f data/logs/news-agent.log
+```
+
+## Backward Compatibility
+
+The system still supports local mail servers if needed:
+
+**For local Postfix:**
+```yaml
+smtp:
+  host: "localhost"
+  port: 25
+  use_tls: false
+  use_ssl: false
+```
+
+No credentials needed in `.env` for localhost delivery.
+
+## Common Use Cases
+
+### 1. Personal Mail Server
+User runs their own mail server at `mail.example.com`:
+- Authenticate with their email credentials
+- Use standard port 587 with TLS
+- Most common use case
+
+### 2. Gmail for Testing
+User wants to test with Gmail:
+- Create App Password in Google account
+- Use `smtp.gmail.com:587`
+- Quick setup for development/testing
+
+### 3. Commercial SMTP Service
+User has SendGrid/Mailgun subscription:
+- Use service's SMTP credentials
+- Higher reliability and deliverability
+- Good for production use
+
+## Documentation Structure
+
+Users should read in this order:
+
+1. **README.md** - Overview and quick start
+2. **SETUP.md** - Step-by-step installation
+3. **SMTP_CONFIG.md** - Detailed SMTP configuration (if issues)
+4. **CHANGES.md** - This file (if migrating from old version)