SurfSense/DEPLOYMENT.md

SurfSense Production Deployment Guide

Server: ai.kapteinis.lv Date: November 17, 2025 Branch: nightly Environment: Debian VPS with local Ollama LLMs

---

📋 Pre-Deployment Checklist

✅ Code Changes Committed:

• Minimal privacy-focused frontend UI
• Email/password authentication only
• Google Analytics removed
• Anthropic Claude removed from examples
• Social media: Mastodon, Pixelfed, Bookwyrm only

✅ GitHub Status:

• All changes pushed to nightly branch
• Repository: https://github.com/okapteinis/SurfSense

✅ Configuration Verified:

• Mistral NeMo 128K context window fix applied
• TildeOpen 30B grammar checker configured
• Gemini API fallback configured
• No secrets committed to repository

---

🚀 Deployment Steps

Option 1: Automated Deployment (Recommended)

# On your VPS (ai.kapteinis.lv)
ssh your-user@ai.kapteinis.lv

# Create deployment script
cat > /opt/SurfSense/deploy.sh << 'EOF'
#!/bin/bash
set -e

echo "🚀 SurfSense Deployment to ai.kapteinis.lv"
echo "==========================================="

# Backup current state
BACKUP_DIR="/opt/SurfSense/backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp -r /opt/SurfSense/surfsense_web "$BACKUP_DIR/"
echo "✅ Backup created: $BACKUP_DIR"

# Pull latest code
cd /opt/SurfSense
git fetch origin
git checkout nightly
git pull origin nightly
echo "✅ Code updated from GitHub"

# Install and build frontend
cd /opt/SurfSense/surfsense_web
pnpm install
pnpm build
echo "✅ Frontend built"

# Restart services
sudo systemctl restart surfsense
sudo systemctl restart surfsense-frontend
sudo systemctl restart surfsense-celery || true
sudo systemctl restart surfsense-celery-beat || true
echo "✅ Services restarted"

# Verify
sleep 5
echo ""
echo "Service Status:"
systemctl is-active surfsense && echo "  ✅ Backend: Running"
systemctl is-active surfsense-frontend && echo "  ✅ Frontend: Running"
systemctl is-active ollama && echo "  ✅ Ollama: Running"

echo ""
echo "🎉 Deployment complete!"
echo "🔗 Visit: https://ai.kapteinis.lv"
EOF

chmod +x /opt/SurfSense/deploy.sh

# Run deployment
/opt/SurfSense/deploy.sh

Option 2: Manual Deployment

# 1. SSH to server
ssh your-user@ai.kapteinis.lv

# 2. Navigate to SurfSense directory
cd /opt/SurfSense

# 3. Backup current installation
mkdir -p backups/$(date +%Y%m%d_%H%M%S)
cp -r surfsense_web backups/$(date +%Y%m%d_%H%M%S)/

# 4. Pull latest changes
git fetch origin
git checkout nightly
git pull origin nightly

# 5. Install frontend dependencies
cd surfsense_web
pnpm install

# 6. Build frontend
pnpm build

# 7. Restart services
sudo systemctl restart surfsense
sudo systemctl restart surfsense-frontend
sudo systemctl restart surfsense-celery
sudo systemctl restart surfsense-celery-beat

# 8. Verify services are running
systemctl status surfsense
systemctl status surfsense-frontend
systemctl status ollama

---

✅ Post-Deployment Verification

1. Check Services Status

# All services should show "active (running)"
sudo systemctl status surfsense
sudo systemctl status surfsense-frontend
sudo systemctl status ollama
sudo systemctl status surfsense-celery

2. Verify UI Changes

Visit https://ai.kapteinis.lv and verify:

Homepage Should Show:

• ✅ SurfSense logo and theme toggle only (no navigation links)
• ✅ "Let's Start Surfing" heading
• ✅ Tagline paragraph
• ✅ Hero screenshot/demo
• ✅ Footer with SurfSense name and social links

Homepage Should NOT Show:

• ❌ "Get Started" button
• ❌ "Pricing" link
• ❌ "Docs" link
• ❌ Discord/GitHub icons
• ❌ "Sign In" button in navbar
• ❌ Feature cards or integrations sections

Login Page Should Show:

• ✅ Email and password fields only
• ✅ "Sign In" button
• ✅ Link to register page

Login Page Should NOT Show:

• ❌ "Continue with Google" button
• ❌ Any OAuth options

3. Test Authentication

# Test login endpoint
curl -X POST https://ai.kapteinis.lv/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"testpass"}'

4. Test LLM Backend

# Check Ollama is running
curl http://localhost:11434/api/tags

# Should show mistral-nemo:128k and tildeopen models

5. Check Logs

# Backend logs
journalctl -u surfsense -n 100 -f

# Frontend logs
journalctl -u surfsense-frontend -n 100 -f

# Ollama logs
journalctl -u ollama -n 100 -f

Look for:

• ✅ No errors during startup
• ✅ "Context window=131072" in logs (Mistral NeMo)
• ✅ Successful model loading messages
• ✅ No Google Analytics references

---

🔧 Troubleshooting

Frontend Build Fails

# Clear cache and rebuild
cd /opt/SurfSense/surfsense_web
rm -rf .next node_modules
pnpm install
pnpm build

Services Won't Start

# Check for errors
journalctl -u surfsense -n 50
journalctl -u surfsense-frontend -n 50

# Verify ports are available
sudo lsof -i :8000  # Backend
sudo lsof -i :3000  # Frontend
sudo lsof -i :11434 # Ollama

Ollama Models Missing

# List installed models
ollama list

# Re-pull if needed
ollama pull mistral-nemo
ollama create mistral-nemo:128k -f /path/to/mistral-nemo-128k.modelfile
ollama pull tildeopen:30b-q5_k_m

Google Analytics Still Showing

# Verify layout.tsx doesn't have GA
grep -r "GoogleAnalytics\|google-analytics\|gtag" /opt/SurfSense/surfsense_web/app/

# Should return nothing

---

📊 Performance Monitoring

After Deployment, Monitor:

# RAM usage (should be 20-25GB during inference)
free -h

# CPU usage
htop

# Disk space
df -h

# Response times
curl -w "@-" -o /dev/null -s https://ai.kapteinis.lv << 'EOF'
time_total: %{time_total}s
EOF

Expected Performance:

• English queries: ~5 seconds
• Latvian queries: ~23 seconds (with grammar check)
• RAM usage: 13-15GB idle, 20-25GB during inference
• Disk usage: ~28GB for Ollama models

---

🔄 Rollback Procedure

If something goes wrong:

# Find backup
ls -lt /opt/SurfSense/backups/

# Restore from backup
cd /opt/SurfSense
mv surfsense_web surfsense_web.failed
cp -r backups/YYYYMMDD_HHMMSS/surfsense_web .

# Restart services
sudo systemctl restart surfsense-frontend

---

📝 Production Configuration

Environment Variables

Location: /opt/SurfSense/surfsense_backend/.env

Required:

GEMINI_API_KEY=your_key_here
OLLAMA_BASE_URL=http://localhost:11434
SECRET_KEY=your_secret_key
DATABASE_URL=postgresql://...
REDIS_URL=redis://localhost:6379

Not Required (Removed):

# GOOGLE_OAUTH_CLIENT_ID  # OAuth disabled
# GOOGLE_OAUTH_CLIENT_SECRET  # OAuth disabled
# ANTHROPIC_API_KEY  # Not using Claude

LLM Configuration

Location: /opt/SurfSense/surfsense_backend/app/config/global_llm_config.yaml

Three-tier architecture:

1. Mistral NeMo 12B (primary)
2. TildeOpen 30B (Latvian grammar)
3. Gemini 2.0 Flash (fallback)

See global_llm_config.yaml.template for structure.

---

🎯 Success Criteria

Deployment is successful when:

• ✅ Homepage shows minimal UI (logo + tagline only)
• ✅ No navigation links visible (Pricing, Docs removed)
• ✅ Login page shows email/password form only
• ✅ No Google OAuth button
• ✅ Footer shows only Mastodon, Pixelfed, Bookwyrm links
• ✅ Services all running (backend, frontend, Ollama)
• ✅ English queries respond in ~5 seconds
• ✅ Latvian queries respond in ~23 seconds
• ✅ No errors in logs
• ✅ RAM usage normal (13-25GB)

---

📞 Support

Issues: https://github.com/okapteinis/SurfSense/issues Email: ojars@kapteinis.lv Deployment Date: November 17, 2025 Version: nightly branch (commit 209cd24)

---

📚 Related Documentation

• INSTALLATION_LOCAL_LLM.md - Complete Ollama setup guide
• MIGRATION_LOCAL_LLM.md - Architecture and migration details
• PR_DESCRIPTION.md - Full PR documentation
• claude.md - Security audit report

---

Deployment Complete! Your minimal, privacy-focused SurfSense instance with local European AI is ready. 🎉