Installation Guide

This guide will help you set up the Event Discovery application with MongoDB integration from scratch.

🚀 Quick Start

# 1. Clone the repository
git clone https://github.com/Reetika12795/Rewind.git
cd inttrest

# 2. Install dependencies
uv sync

# 3. Configure environment
cp .env.example .env
# Edit .env with your credentials

# 4. Test the setup
python test_mongo.py

📋 Prerequisites

System Requirements

graph TB
    subgraph "Required"
        REQ1[Python 3.8+]
        REQ2[uv package manager]
        REQ3[Git]
        REQ4[MongoDB Atlas account]
    end

    subgraph "Optional"
        OPT1[Node.js 18+ for MCP]
        OPT2[Docker for containers]
        OPT3[Google Maps API key]
    end

    style REQ1 fill:#ffebee
    style OPT1 fill:#e8f5e8

Check Your System

# Check Python version
python --version
# Should output: Python 3.8.x or higher

# Check if uv is installed
uv --version
# Should output: uv x.x.x

# Install uv if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

🔧 Installation Steps

Step 1: Repository Setup

# Clone the repository
git clone https://github.com/Reetika12795/Rewind.git

# Navigate to the project directory
cd Rewind/inttrest

# Check the project structure
ls -la

Expected structure:

inttrest/
├── mongo_connector.py      # MongoDB interface
├── geocoder.py            # Geocoding service
├── save_events.py         # Event processing
├── test_mongo.py          # Database tests
├── pyproject.toml         # Project configuration
├── requirements.txt       # Dependencies
└── docs/                  # Documentation

Step 2: Dependencies Installation

# Install Python dependencies using uv
uv sync

# Alternative: Using pip (if uv fails)
pip install -r requirements.txt

Expected output:

Resolved 26 packages in 2s
Installed 26 packages in 500ms
 + pymongo==4.6.0
 + requests==2.31.0
 + ...

Step 3: Environment Configuration

# Create environment file from template
cp .env.example .env

# Edit the environment file
nano .env  # or use your preferred editor

Required environment variables:

# MongoDB Atlas Configuration
MONGODB_PASSWORD=your_mongodb_atlas_password

# Optional: Geocoding API keys
GOOGLE_GEOCODING_API_KEY=your_google_api_key

# Optional: MCP Server URLs
EVENTBRITE_MCP_URL=http://localhost:3001
MEETUP_MCP_URL=http://localhost:3002
LINKEDIN_MCP_URL=http://localhost:3003

🗄️ MongoDB Atlas Setup

Step 1: Create MongoDB Atlas Account

1. Visit MongoDB Atlas
2. Sign up for a free account
3. Create a new project named "Event Discovery"
4. Deploy a free cluster (M0 Sandbox)

Step 2: Configure Database Access

sequenceDiagram
    participant You
    participant Atlas as MongoDB Atlas
    participant App as Your Application

    You->>Atlas: Create Database User
    Atlas-->>You: Username/Password

    You->>Atlas: Add IP to Access List
    Atlas-->>You: Network Access Granted

    You->>Atlas: Get Connection String
    Atlas-->>You: Connection URI

    You->>App: Configure with credentials
    App->>Atlas: Test Connection
    Atlas-->>App: Connection Successful

Create Database User

1. Navigate to Database Access → Add New Database User
2. Authentication Method: Password
3. Username: event_user (or your choice)
4. Password: Generate secure password
5. Database User Privileges: Read and write to any database
6. Click Add User

Configure Network Access

1. Navigate to Network Access → Add IP Address
2. Access List Entry:
3. For development: 0.0.0.0/0 (allow from anywhere)
4. For production: Your specific IP address
5. Click Confirm

Get Connection String

1. Navigate to Clusters → Connect
2. Choose Connect your application
3. Driver: Python, Version 3.6+
4. Copy the connection string
5. Replace <password> with your actual password

Example connection string:

mongodb+srv://event_user:<password>@cluster0.mongodb.net/events_db?retryWrites=true&w=majority

Step 3: Test Database Connection

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# Test the connection
python test_mongo.py

Expected output:

✅ Connected to MongoDB!
✅ Event inserted: Test Event
✅ Inserted 2 events
🔍 Finding events...
- Test Event in Paris
- Batch Event 1 in Paris
📊 Total events in database: 3
🔐 MongoDB connection closed

🧪 Testing Your Setup

Basic Functionality Test

# Create test file: test_setup.py
from mongo_connector import MongoConnector
from geocoder import geocoder
import os

def test_complete_setup():
    """Test all components are working"""

    print("🧪 Testing complete setup...")

    # 1. Test MongoDB connection
    try:
        password = os.getenv("MONGODB_PASSWORD")
        if not password:
            password = input("Enter MongoDB password: ")

        mongo = MongoConnector(password)
        print("✅ MongoDB connection successful")

        # Test basic operations
        count = mongo.count_events()
        print(f"📊 Current events in database: {count}")

        mongo.close()

    except Exception as e:
        print(f"❌ MongoDB test failed: {e}")
        return False

    # 2. Test geocoding service
    try:
        test_address = "15 rue de milan, paris"
        coords = geocoder.geocode(test_address)

        if coords:
            print(f"✅ Geocoding successful: {coords}")
        else:
            print("⚠️ Geocoding returned no results")

    except Exception as e:
        print(f"❌ Geocoding test failed: {e}")
        return False

    # 3. Test event processing
    try:
        from save_events import save_mcp_events

        # Mock event data
        mock_events = [{
            "id": "test_setup_001",
            "title": "Setup Test Event",
            "location": "Paris, France",
            "category": "Technology"
        }]

        saved_count = save_mcp_events(mock_events, "test", password)
        print(f"✅ Event processing successful: {saved_count} events saved")

    except Exception as e:
        print(f"❌ Event processing test failed: {e}")
        return False

    print("🎉 All tests passed! Setup is complete.")
    return True

if __name__ == "__main__":
    test_complete_setup()

Run the Comprehensive Test

python test_setup.py

🔍 Troubleshooting

Common Issues and Solutions

Issue: ModuleNotFoundError: No module named 'pymongo'

Solution:

# Ensure you're in the correct environment
source .venv/bin/activate

# Reinstall dependencies
uv sync

# Or force reinstall
pip install --force-reinstall pymongo

Issue: MongoDB connection fails

Solutions:

1. Check credentials:

   # Verify your .env file
   cat .env | grep MONGODB_PASSWORD
   

2. Check network access:

3. Ensure your IP is in the MongoDB Atlas access list

4. Try 0.0.0.0/0 for testing (not recommended for production)

5. Check connection string:

   # Test with manual connection string
   from pymongo import MongoClient
   
   uri = "mongodb+srv://username:password@cluster.mongodb.net/"
   client = MongoClient(uri)
   client.admin.command('ping')  # Should not raise exception
   

Issue: Geocoding not working

Solutions:

1. Check internet connection:

   curl -I https://nominatim.openstreetmap.org
   

2. Check rate limiting:

   # Increase delay between requests
   import time
   time.sleep(2)  # Wait 2 seconds instead of 1
   

3. Try alternative address formats:

   addresses = [
       "15 rue de milan, paris",
       "15 Rue de Milan, Paris, France",
       "rue de Milan, 75009 Paris"
   ]
   

Issue: uv command not found

Solution:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Restart terminal or source profile
source ~/.bashrc  # or ~/.zshrc

# Verify installation
uv --version

Issue: Permission errors on macOS/Linux

Solution:

# Fix permissions
chmod +x setup_scripts/*.sh

# Use sudo if needed for system-wide installation
sudo pip install -r requirements.txt

🚀 Next Steps

After successful installation:

1. 📖 Read the documentation:

   # Build and serve documentation
   mkdocs serve
   # Visit: http://localhost:8000
   

2. 🧑‍💻 Set up colleague access:

   python colleague_setup.py
   

3. 🔗 Configure MCP servers (optional):

   # Follow MCP setup guide
   python setup_mcp_servers.py
   

4. 🎨 Set up frontend (optional):

   cd frontend
   npm install
   npm run dev
   

Development Workflow

graph LR
    A[Code Changes] --> B[Test Locally]
    B --> C[Run Tests]
    C --> D[Update Docs]
    D --> E[Commit & Push]

    style A fill:#e3f2fd
    style C fill:#e8f5e8
    style E fill:#fff3e0

📚 Additional Resources

• MongoDB Atlas Documentation
• uv Package Manager Guide
• OpenStreetMap Nominatim API
• MkDocs Material Theme

🆘 Getting Help

If you encounter issues:

1. Check the logs for error details
2. Review this troubleshooting section
3. Search existing issues on GitHub
4. Create a new issue with detailed error information

Issue Template:

## Environment
- OS: [e.g., macOS 12.0]
- Python: [e.g., 3.9.7]
- uv: [e.g., 0.1.0]

## Error Description
[Describe what you were trying to do]

## Error Output

[Paste complete error message]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [etc.]

Your setup should now be complete and ready for development! 🎉