8b9f946a4a
Complete migration to ProtonBridge following proven family-history architecture: Backend Changes: - Replace @sendgrid/mail with nodemailer - Refactor EmailService for ProtonBridge/SMTP - Add smart port detection (1026 prod, 1025 dev) - Implement connection pooling and rate limiting - Add EMAIL_ENABLED flag for dev/prod separation - Add checkConnection() method for health checks Email Service Features: - Localhost-only SMTP (127.0.0.1) - Automatic production/development port detection - Connection verification on initialization - Connection pooling (max 5 connections) - Rate limiting (10 messages/second) - Graceful fallback when email disabled Documentation: - Complete ProtonBridge setup guide (VPS installation) - Quick start guide (30-minute setup) - Systemd service file template - Environment variable configuration - Troubleshooting guide - Migration notes from SendGrid Architecture Benefits: - Privacy-focused (end-to-end encrypted via Proton) - Self-hosted bridge on VPS (no third-party API) - Validated in production (family-history: 3+ months, 315+ restarts) - Cost-effective (Proton paid account ~$4/month) - No external dependencies (localhost SMTP) Next Steps: 1. Install ProtonBridge on production VPS 2. Update production .env with Bridge credentials 3. Deploy email service changes 4. Test newsletter sending See docs/PROTONBRIDGE_QUICKSTART.md for deployment guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
152 lines
3.5 KiB
Markdown
152 lines
3.5 KiB
Markdown
# ProtonBridge Quick Start Guide
|
|
|
|
**Time Required**: ~30 minutes
|
|
**Prerequisites**: Paid Proton account, SSH access to VPS
|
|
|
|
---
|
|
|
|
## 1. Install ProtonBridge on VPS (10 min)
|
|
|
|
```bash
|
|
# SSH to production
|
|
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net
|
|
|
|
# Install dependencies
|
|
sudo apt-get update && sudo apt-get install -y pass gnupg xvfb
|
|
|
|
# Download and install ProtonBridge
|
|
wget https://proton.me/download/bridge/protonmail-bridge_3.0.21-1_amd64.deb
|
|
sudo dpkg -i protonmail-bridge_3.0.21-1_amd64.deb
|
|
sudo apt-get install -f
|
|
|
|
# Configure GPG/pass
|
|
gpg --gen-key # Follow prompts
|
|
pass init "YOUR_GPG_KEY_ID" # Use key ID from previous step
|
|
|
|
# Configure ProtonBridge
|
|
protonmail-bridge --cli
|
|
> login # Enter Proton credentials
|
|
> info # ⚠️ COPY THE BRIDGE PASSWORD
|
|
> exit
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Install Systemd Service (5 min)
|
|
|
|
```bash
|
|
# Copy service file from repo
|
|
sudo cp /var/www/tractatus/scripts/protonmail-bridge.service /etc/systemd/system/
|
|
|
|
# Enable and start
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable protonmail-bridge
|
|
sudo systemctl start protonmail-bridge
|
|
|
|
# Verify
|
|
sudo systemctl status protonmail-bridge # Should show "active (running)"
|
|
nc -zv 127.0.0.1 1026 # Should connect
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Update Production Environment (5 min)
|
|
|
|
```bash
|
|
# Edit .env on production server
|
|
nano /var/www/tractatus/.env
|
|
|
|
# Add these lines (replace with your values):
|
|
EMAIL_ENABLED=true
|
|
EMAIL_PROVIDER=proton
|
|
SMTP_HOST=127.0.0.1
|
|
SMTP_PORT=1026
|
|
SMTP_SECURE=false
|
|
SMTP_USER=your-tractatus-email@pm.me
|
|
SMTP_PASS=BRIDGE_PASSWORD_FROM_STEP_1
|
|
EMAIL_FROM=your-tractatus-email@pm.me
|
|
|
|
# Save and exit (Ctrl+X, Y, Enter)
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Deploy & Test (10 min)
|
|
|
|
```bash
|
|
# From local machine
|
|
cd /home/theflow/projects/tractatus
|
|
|
|
# Deploy email service changes
|
|
./scripts/deploy.sh src/services/email.service.js --restart
|
|
|
|
# Test email service
|
|
curl -s https://agenticgovernance.digital/health/detailed | jq '.services.email'
|
|
|
|
# Should show: { "status": "running", "smtp": { "status": "connected", ... } }
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Send Test Email
|
|
|
|
1. Access the newsletter administration interface (admin authentication required)
|
|
2. Select tier: "Research Updates"
|
|
3. Subject: "ProtonBridge Test"
|
|
4. Content JSON:
|
|
```json
|
|
{
|
|
"highlight_1_title": "Test",
|
|
"highlight_1_summary": "Testing ProtonBridge",
|
|
"highlight_1_link": "https://agenticgovernance.digital",
|
|
"finding_1": "ProtonBridge works!",
|
|
"question_1": "Is email sending working?",
|
|
"feedback_link": "https://agenticgovernance.digital",
|
|
"blog_link": "https://agenticgovernance.digital"
|
|
}
|
|
```
|
|
5. Click "Send Test"
|
|
6. Enter your email address
|
|
7. Check inbox ✅
|
|
|
|
---
|
|
|
|
## Common Issues
|
|
|
|
### "SMTP connection verification failed"
|
|
```bash
|
|
# Restart ProtonBridge
|
|
sudo systemctl restart protonmail-bridge
|
|
sleep 30 # Wait for sync
|
|
sudo systemctl restart tractatus
|
|
```
|
|
|
|
### "Authentication failed"
|
|
- Check SMTP_PASS is the **Bridge password** (from `protonmail-bridge --cli > info`)
|
|
- NOT your Proton account password!
|
|
|
|
### Emails not received
|
|
- Check spam folder
|
|
- Verify Proton account has sending quota available
|
|
- Check ProtonBridge logs: `sudo journalctl -u protonmail-bridge -n 50`
|
|
|
|
---
|
|
|
|
## Monitoring
|
|
|
|
```bash
|
|
# ProtonBridge status
|
|
sudo systemctl status protonmail-bridge
|
|
|
|
# Email service logs
|
|
sudo journalctl -u tractatus -f | grep EmailService
|
|
|
|
# Port check
|
|
ss -tuln | grep 1026
|
|
```
|
|
|
|
---
|
|
|
|
**Done!** Email sending is now using ProtonBridge instead of SendGrid.
|
|
|
|
For detailed documentation, see: `docs/PROTONBRIDGE_SETUP.md`
|