# 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`