Munich-news/docs/REFERENCE.md

Quick Reference

Essential commands and information.

---

Quick Start

# Start services
./start-with-gpu.sh              # With GPU auto-detection
docker-compose up -d             # Without GPU

# Stop services
docker-compose down

# View logs
docker-compose logs -f
docker-compose logs -f crawler   # Specific service

# Restart
docker-compose restart

---

Docker Commands

# Service status
docker-compose ps

# Rebuild
docker-compose up -d --build

# Execute command in container
docker-compose exec backend python -c "print('hello')"
docker-compose exec crawler python crawler_service.py 2

# View container logs
docker logs munich-news-backend
docker logs munich-news-crawler

# Resource usage
docker stats

---

API Commands

# Health check
curl http://localhost:5001/health

# System stats
curl http://localhost:5001/api/admin/stats

# Trigger crawl
curl -X POST http://localhost:5001/api/admin/trigger-crawl \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 5}'

# Send test email
curl -X POST http://localhost:5001/api/admin/send-test-email \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

# Send newsletter to all
curl -X POST http://localhost:5001/api/admin/send-newsletter \
  -H "Content-Type: application/json" \
  -d '{"max_articles": 10}'

---

GPU Commands

# Check GPU availability
./check-gpu.sh

# Start with GPU
./start-with-gpu.sh
docker-compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

# Check GPU usage
docker exec munich-news-ollama nvidia-smi

# Monitor GPU
watch -n 1 'docker exec munich-news-ollama nvidia-smi'

---

MongoDB Commands

# Access MongoDB shell
docker-compose exec mongodb mongosh munich_news -u admin -p changeme --authenticationDatabase admin

# Count documents
db.articles.countDocuments({})
db.subscribers.countDocuments({status: 'active'})

# Find articles
db.articles.find().limit(5).pretty()

# Clear articles
db.articles.deleteMany({})

# Add subscriber
db.subscribers.insertOne({
  email: "user@example.com",
  subscribed_at: new Date(),
  status: "active"
})

---

Testing Commands

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

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

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

# Test crawl (2 articles)
docker-compose exec crawler python crawler_service.py 2

---

Configuration

Single .env File

Location: backend/.env

Key Settings:

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

# Email
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
EMAIL_USER=your@email.com
EMAIL_PASSWORD=your-password

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

---

Port Exposure

Service	Port	Exposed	Access
Backend	5001	✅ Yes	Host, External
MongoDB	27017	❌ No	Internal only
Ollama	11434	❌ No	Internal only
Crawler	-	❌ No	Internal only
Sender	-	❌ No	Internal only

Verify:

docker ps --format "table {{.Names}}\t{{.Ports}}"

---

Performance

CPU Mode

• Translation: ~1.5s per title
• Summarization: ~8s per article
• 10 Articles: ~115s

GPU Mode (5-10x faster)

• Translation: ~0.3s per title
• Summarization: ~2s per article
• 10 Articles: ~31s

---

Troubleshooting

Service Won't Start

docker-compose logs <service-name>
docker-compose restart <service-name>
docker-compose up -d --build <service-name>

MongoDB Connection Issues

# Check service
docker-compose ps mongodb

# Test connection
docker-compose exec backend python -c "from database import articles_collection; print(articles_collection.count_documents({}))"

Ollama Issues

# Check model
docker-compose exec ollama ollama list

# Pull model manually
docker-compose exec ollama ollama pull phi3:latest

# Check logs
docker-compose logs ollama

GPU Not Working

# Check GPU
nvidia-smi

# Check Docker GPU access
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

# Check Ollama GPU
docker exec munich-news-ollama nvidia-smi

---

Recent Updates (November 2025)

New Features

• ✅ GPU acceleration (5-10x faster)
• ✅ Integrated Ollama service
• ✅ Send newsletter to all subscribers API
• ✅ Article title translation (German → English)
• ✅ Enhanced security (network isolation)

Security Improvements

• MongoDB internal-only (not exposed)
• Ollama internal-only (not exposed)
• Only Backend API exposed (port 5001)
• 66% reduction in attack surface

Configuration Changes

• MongoDB URI uses mongodb (not localhost)
• Ollama URL uses http://ollama:11434
• Single .env file in backend/

New Scripts

• start-with-gpu.sh - Auto-detect GPU and start
• check-gpu.sh - Check GPU availability
• test-ollama-setup.sh - Test Ollama
• test-mongodb-connectivity.sh - Test MongoDB
• test-newsletter-api.sh - Test newsletter API

---

Changelog

November 2025

• Added GPU acceleration support
• Integrated Ollama into Docker Compose
• Added newsletter API endpoint
• Improved network security
• Added article title translation
• Consolidated documentation
• Added helper scripts

Key Changes

• Ollama now runs in Docker (no external server needed)
• MongoDB and Ollama are internal-only
• GPU support with automatic detection
• Subscriber status system documented
• All docs consolidated and updated

---

Links

• Setup Guide: SETUP.md
• API Reference: API.md
• Architecture: ARCHITECTURE.md
• Security: SECURITY.md
• Features: FEATURES.md

---

Last Updated: November 2025