gcp-hockey-results/motm_app/SETUP_GUIDE.md

MOTM Application - Virtual Environment Setup Guide

This guide will help you set up a Python virtual environment for the MOTM Flask application.

Prerequisites

1. Python 3.7 or higher must be installed on your system
2. pip package manager should be available

Quick Setup (Windows)

Step 1: Check Python Installation

Open Command Prompt or PowerShell and run:

python --version

If Python is not found, you may need to:

• Install Python from python.org
• Or use py command if you have Python Launcher installed

Step 2: Create Virtual Environment

Navigate to the motm_app directory and run:

Option A: Using python command

python -m venv venv

Option B: Using py command (if available)

py -m venv venv

Option C: Using full path (if needed)

C:\Python39\python.exe -m venv venv

Step 3: Activate Virtual Environment

Windows Command Prompt:

venv\Scripts\activate.bat

Windows PowerShell:

venv\Scripts\Activate.ps1

Step 4: Install Dependencies

With the virtual environment activated:

pip install --upgrade pip
pip install -r requirements.txt

Step 5: Run the Application

python main.py

The application will be available at: http://localhost:5000

Quick Setup (Unix/Linux/Mac)

Step 1: Create Virtual Environment

python3 -m venv venv

Step 2: Activate Virtual Environment

source venv/bin/activate

Step 3: Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

Step 4: Run the Application

python main.py

Using the Convenience Scripts

After setting up the virtual environment, you can use the provided scripts:

Windows

• Setup: setup_venv_windows.bat
• Activate: activate_motm.bat
• Run: run_motm.bat

Unix/Linux/Mac

• Activate: source activate_motm.sh
• Run: ./run_motm.sh

Troubleshooting

Python Not Found

Windows:

1. Install Python from python.org
2. During installation, check "Add Python to PATH"
3. Restart your command prompt

Alternative for Windows:

1. Install Python from Microsoft Store
2. Use py command instead of python

Virtual Environment Issues

Permission Errors (Windows):

# Try running as Administrator
# Or use PowerShell with execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Virtual Environment Already Exists:

# Remove existing environment
rmdir /s venv
# Or on Unix/Linux/Mac
rm -rf venv

Dependencies Not Installing

1. Activate virtual environment first
2. Upgrade pip: pip install --upgrade pip
3. Install individually: pip install Flask
4. Check internet connection
5. Try using --user flag: pip install --user -r requirements.txt

Application Not Starting

1. Check virtual environment is activated (should see (venv) in prompt)
2. Verify all dependencies installed: pip list
3. Check for import errors: python -c "import flask"
4. Review error messages in console output

Development Workflow

Daily Usage

1. Activate environment: venv\Scripts\activate.bat (Windows) or source venv/bin/activate (Unix)
2. Make changes to your code
3. Test application: python main.py
4. Deactivate when done: deactivate

Adding New Packages

1. Activate environment
2. Install package: pip install new-package
3. Update requirements: pip freeze > requirements.txt
4. Commit changes to version control

Updating Dependencies

1. Activate environment
2. Update packages: pip install --upgrade package-name
3. Update requirements: pip freeze > requirements.txt

Environment Variables

If you need to set environment variables for the application:

Windows:

set DATABASE_URL=your_database_url
python main.py

Unix/Linux/Mac:

export DATABASE_URL=your_database_url
python main.py

Database Configuration

Make sure to update db_config.py with your database connection details before running the application.

Getting Help

If you encounter issues:

1. Check Python version: Should be 3.7 or higher
2. Verify virtual environment: Should be activated
3. Check dependencies: Run pip list to see installed packages
4. Review error messages: Look for specific error details
5. Test imports: python -c "import flask, pymysql"

Production Deployment

For production deployment:

1. Use same Python version as development
2. Install exact dependencies: pip install -r requirements.txt
3. Set environment variables for production database
4. Configure web server (nginx, Apache, etc.)
5. Use process manager (systemd, supervisor, etc.)

---

Note: This application requires access to the existing hockey results database. Ensure proper database connectivity before running.