tractatus/docs/PROTONBRIDGE_QUICKSTART.md

ProtonBridge Quick Start Guide

Time Required: ~30 minutes Prerequisites: Paid Proton account, SSH access to VPS

---

1. Install ProtonBridge on VPS (10 min)

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

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

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

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

   {
     "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"

# 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

# 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