Munich-news/docs/SETUP.md

# Complete Setup Guide

## Quick Start

```bash
# 1. Configure
cp backend/.env.example backend/.env
# Edit backend/.env with your email settings

# 2. Start (with GPU auto-detection)
./start-with-gpu.sh

# 3. Wait for model download (first time, ~2-5 min)
docker-compose logs -f ollama-setup
```

---

## Prerequisites

- Docker & Docker Compose
- 4GB+ RAM
- (Optional) NVIDIA GPU for 5-10x faster AI

---

## Configuration

### Environment File

Edit `backend/.env`:

```env
# Email (Required)
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

# MongoDB (Docker service name)
MONGODB_URI=mongodb://admin:changeme@mongodb:27017/

# Ollama AI (Internal Docker network)
OLLAMA_ENABLED=true
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=phi3:latest
```

---

## Ollama Setup

### Integrated Docker Compose (Recommended)

Ollama runs automatically with Docker Compose:
- Automatic model download (phi3:latest, 2.2GB)
- Internal-only access (secure)
- Persistent storage
- GPU support available

**Start:**
```bash
docker-compose up -d
```

**Verify:**
```bash
docker-compose exec ollama ollama list
# Should show: phi3:latest
```

---

## GPU Acceleration (5-10x Faster)

### Check GPU Availability

```bash
./check-gpu.sh
```

### Start with GPU

```bash
# Auto-detect and start
./start-with-gpu.sh

# Or manually
docker-compose -f docker-compose.yml -f docker-compose.gpu.yml up -d
```

### Verify GPU Usage

```bash
# Check GPU
docker exec munich-news-ollama nvidia-smi

# Monitor during processing
watch -n 1 'docker exec munich-news-ollama nvidia-smi'
```

### Performance

| Operation | CPU | GPU | Speedup |
|-----------|-----|-----|---------|
| Translation | 1.5s | 0.3s | 5x |
| Summary | 8s | 2s | 4x |
| 10 Articles | 115s | 31s | 3.7x |

### GPU Requirements

- NVIDIA GPU (GTX 1060 or newer)
- 4GB+ VRAM for phi3:latest
- NVIDIA drivers (525.60.13+)
- NVIDIA Container Toolkit

**Install NVIDIA Container Toolkit (Ubuntu/Debian):**
```bash
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```

---

## Production Deployment

### Security Checklist

- [ ] Change MongoDB password
- [ ] Use strong email password
- [ ] Bind backend to localhost only: `127.0.0.1:5001:5001`
- [ ] Set up reverse proxy (nginx/Traefik)
- [ ] Enable HTTPS
- [ ] Set up firewall rules
- [ ] Regular backups
- [ ] Monitor logs

### Reverse Proxy (nginx)

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:5001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### Environment Variables

For production, use environment variables instead of .env:

```bash
export MONGODB_URI="mongodb://user:pass@mongodb:27017/"
export SMTP_SERVER="smtp.gmail.com"
export EMAIL_PASSWORD="secure-password"
```

### Monitoring

```bash
# Check service health
docker-compose ps

# View logs
docker-compose logs -f

# Check resource usage
docker stats
```

---

## Troubleshooting

### Ollama Issues

**Model not downloading:**
```bash
docker-compose logs ollama-setup
docker-compose exec ollama ollama pull phi3:latest
```

**Out of memory:**
- Use smaller model: `OLLAMA_MODEL=gemma2:2b`
- Increase Docker memory limit

### GPU Issues

**GPU not detected:**
```bash
nvidia-smi  # Check drivers
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi  # Check Docker
```

**Out of VRAM:**
- Use smaller model
- Close other GPU applications

### MongoDB Issues

**Connection refused:**
- Check service is running: `docker-compose ps`
- Verify URI uses `mongodb` not `localhost`

### Email Issues

**Authentication failed:**
- Use app-specific password (Gmail)
- Check SMTP settings
- Verify credentials

---

## Testing

```bash
# Test Ollama
./test-ollama-setup.sh

# Test MongoDB
./test-mongodb-connectivity.sh

# Test newsletter
./test-newsletter-api.sh

# Test crawl
docker-compose exec crawler python crawler_service.py 2
```

---

## Next Steps

1. Add RSS feeds (see QUICKSTART.md)
2. Add subscribers
3. Test newsletter sending
4. Set up monitoring
5. Configure backups

See [API.md](API.md) for API reference.