gcp-hockey-results/motm_app/VIRTUAL_ENV_GUIDE.md

# MOTM Application - Virtual Environment Guide

## 🎯 Why Use Virtual Environments?

Virtual environments provide **isolated Python environments** for your projects, which means:

- ✅ **No conflicts** between different project dependencies
- ✅ **Reproducible environments** across different machines
- ✅ **Clean separation** of project requirements
- ✅ **Easy deployment** with exact dependency versions

## 🚀 Quick Start

### Windows Users

1. **Open Command Prompt** (not PowerShell initially)
2. **Navigate to motm_app directory**:
   ```cmd
   cd path\to\motm_app
   ```

3. **Create virtual environment**:
   ```cmd
   python -m venv venv
   ```
   *If this fails, try `py -m venv venv` or find your Python installation*

4. **Activate virtual environment**:
   ```cmd
   venv\Scripts\activate.bat
   ```
   *You should see `(venv)` at the beginning of your command prompt*

5. **Install dependencies**:
   ```cmd
   pip install --upgrade pip
   pip install -r requirements.txt
   ```

6. **Run the application**:
   ```cmd
   python main.py
   ```

### Mac/Linux Users

1. **Open Terminal**
2. **Navigate to motm_app directory**:
   ```bash
   cd path/to/motm_app
   ```

3. **Create virtual environment**:
   ```bash
   python3 -m venv venv
   ```

4. **Activate virtual environment**:
   ```bash
   source venv/bin/activate
   ```
   *You should see `(venv)` at the beginning of your command prompt*

5. **Install dependencies**:
   ```bash
   pip install --upgrade pip
   pip install -r requirements.txt
   ```

6. **Run the application**:
   ```bash
   python main.py
   ```

## 📁 What Gets Created

When you create a virtual environment, you'll see a new `venv` folder:

```
motm_app/
├── venv/                    # Virtual environment (don't edit this)
│   ├── Scripts/            # Windows activation scripts
│   ├── bin/                # Unix activation scripts  
│   ├── Lib/                # Installed packages
│   └── pyvenv.cfg          # Environment configuration
├── main.py                 # Your application
├── requirements.txt        # Dependencies list
└── ...                     # Other files
```

## 🔧 Daily Usage

### Starting Your Work Session

1. **Activate the virtual environment**:
   - Windows: `venv\Scripts\activate.bat`
   - Mac/Linux: `source venv/bin/activate`

2. **Verify activation** - you should see `(venv)` in your prompt:
   ```cmd
   (venv) C:\path\to\motm_app>
   ```

3. **Run your application**:
   ```cmd
   python main.py
   ```

### Ending Your Work Session

**Deactivate when done**:
```cmd
deactivate
```
*The `(venv)` indicator will disappear*

## 📦 Managing Dependencies

### Installing New Packages

1. **Activate virtual environment first**
2. **Install the package**:
   ```cmd
   pip install package-name
   ```

3. **Update requirements.txt**:
   ```cmd
   pip freeze > requirements.txt
   ```

4. **Commit the updated requirements.txt** to version control

### Updating Existing Packages

```cmd
pip install --upgrade package-name
```

### Viewing Installed Packages

```cmd
pip list
```

### Removing Packages

```cmd
pip uninstall package-name
```

## 🛠️ Troubleshooting

### "Python not found" Error

**Windows:**
- Install Python from [python.org](https://www.python.org/downloads/)
- During installation, check "Add Python to PATH"
- Try using `py` command instead of `python`

**Mac/Linux:**
- Install Python 3: `brew install python3` (Mac) or use package manager
- Use `python3` instead of `python`

### Virtual Environment Won't Activate

**Windows:**
```cmd
# Try running Command Prompt as Administrator
# Or use PowerShell with:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

**Permission Errors:**
```cmd
# Remove and recreate
rmdir /s venv          # Windows
rm -rf venv            # Mac/Linux
python -m venv venv    # Recreate
```

### Packages Not Found After Installation

1. **Make sure virtual environment is activated** (look for `(venv)`)
2. **Check if packages are installed**: `pip list`
3. **Reinstall requirements**: `pip install -r requirements.txt`

### Application Won't Start

1. **Activate virtual environment**
2. **Check all dependencies**: `pip install -r requirements.txt`
3. **Test imports**: `python -c "import flask"`
4. **Check error messages** in the console

## 🔄 Working with Teams

### Sharing Your Environment

1. **Commit `requirements.txt`** to version control
2. **Don't commit the `venv` folder** (add to `.gitignore`)

### Setting Up on New Machine

1. **Clone the repository**
2. **Create virtual environment**: `python -m venv venv`
3. **Activate it**: `venv\Scripts\activate.bat` (Windows) or `source venv/bin/activate` (Unix)
4. **Install dependencies**: `pip install -r requirements.txt`

## 🚀 Deployment Considerations

### Production Environment

- Use the same Python version as development
- Install exact dependencies: `pip install -r requirements.txt`
- Set up environment variables for database connections
- Use a proper web server (nginx, Apache)
- Consider using Docker for containerization

### Docker Example

```dockerfile
FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "main.py"]
```

## 💡 Best Practices

1. **Always use virtual environments** for Python projects
2. **Activate before working** on the project
3. **Keep requirements.txt updated** when adding packages
4. **Use descriptive commit messages** when updating dependencies
5. **Test your application** after installing new packages
6. **Document any special setup requirements**

## 🆘 Getting Help

If you're still having issues:

1. **Check Python version**: Should be 3.7 or higher
2. **Verify virtual environment**: Should be activated (see `(venv)` in prompt)
3. **Review error messages**: Look for specific error details
4. **Test step by step**: Create a simple test script to verify Python works
5. **Check internet connection**: Required for installing packages

---

**Remember**: The virtual environment isolates your project dependencies from your system Python installation, making your project more reliable and portable! 🎉