ENV_SETUP.md

# Environment Variables Setup Guide

This guide explains how to set the required environment variables for the IITM LLM Quiz Solver.

## Required Variables

- `QUIZ_SECRET`: Secret key for API authentication (required)
- `OPENAI_API_KEY`: OpenAI API key for LLM features (optional)
- `OPENROUTER_API_KEY`: OpenRouter key (e.g., GPT-5-nano) – optional fallback or alternative

---

## Method 1: Windows (PowerShell)

### Temporary (Current Session Only)

Open PowerShell and run:

```powershell
$env:QUIZ_SECRET = "EasyQuiZ"
$env:OPENAI_API_KEY = "sk-your-openai-api-key-here"
$env:OPENROUTER_API_KEY = "sk-or-your-openrouter-key"
```

### Permanent (System-Wide)

1. **Using PowerShell (Admin):**
```powershell
[System.Environment]::SetEnvironmentVariable("QUIZ_SECRET", "your_secret_key_here", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-openai-api-key-here", "User")
[System.Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-your-openrouter-key", "User")
```

2. **Using GUI:**
   - Press `Win + R`, type `sysdm.cpl`, press Enter
   - Go to "Advanced" tab → Click "Environment Variables"
   - Under "User variables", click "New"
   - Add `QUIZ_SECRET` with your value
   - Add `OPENAI_API_KEY` with your value
   - Click OK to save

### Using .env File (Recommended for Development)

1. Create a `.env` file in the project root:
```env
QUIZ_SECRET=your_secret_key_here
OPENAI_API_KEY=sk-your-openai-api-key-here
OPENROUTER_API_KEY=sk-or-your-openrouter-key
```

2. Install python-dotenv:
```bash
pip install python-dotenv
```

3. Update `app/main.py` to load .env file (add at the top):
```python
from dotenv import load_dotenv
load_dotenv()
```

---

## Method 2: Linux/Mac (Bash)

### Temporary (Current Session Only)

Open terminal and run:

```bash
export QUIZ_SECRET="your_secret_key_here"
export OPENAI_API_KEY="sk-your-openai-api-key-here"
export OPENROUTER_API_KEY="sk-or-your-openrouter-key"
```

### Permanent (Add to Shell Profile)

Add to `~/.bashrc` or `~/.zshrc`:

```bash
echo 'export QUIZ_SECRET="your_secret_key_here"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="sk-your-openai-api-key-here"' >> ~/.bashrc
echo 'export OPENROUTER_API_KEY="sk-or-your-openrouter-key"' >> ~/.bashrc
source ~/.bashrc
```

### Using .env File (Recommended for Development)

Same as Windows method above.

---

## Method 3: Hugging Face Spaces

### Step-by-Step Instructions

1. **Go to your Space:**
   - Navigate to https://huggingface.co/spaces
   - Open your Space

2. **Access Settings:**
   - Click on "Settings" in the top menu
   - Select "Variables and secrets" from the left sidebar

3. **Add Variables:**
   - Click "New variable" or "New secret"
   - For `QUIZ_SECRET`:
     - Key: `QUIZ_SECRET`
     - Value: Your secret key
     - Type: Variable (or Secret if you want it hidden)
   - For `OPENAI_API_KEY`:
     - Key: `OPENAI_API_KEY`
     - Value: Your OpenAI API key (starts with `sk-`)
     - Type: Secret (recommended for API keys)

4. **Save:**
   - Click "Save" or "Add variable"
   - The Space will automatically rebuild with new variables

### Important Notes for HF Spaces:
- Variables are available to your Docker container
- Secrets are hidden from logs but accessible in code
- Changes require a rebuild (automatic)
- `PORT` is usually set automatically by HF Spaces

---

## Method 4: Docker (Local)

### Using docker run:

```bash
docker run -e QUIZ_SECRET="your_secret" -e OPENAI_API_KEY="sk-your-key" -p 8000:8000 your-image
```

### Using docker-compose.yml:

Create `docker-compose.yml`:

```yaml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - QUIZ_SECRET=${QUIZ_SECRET}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    env_file:
      - .env  # Optional: load from .env file
```

Then run:
```bash
docker-compose up
```

---

## Verification

### Method 1: Using the Check Script (Easiest)

Run the included verification script:

```bash
python check_env.py
```

This will show:
- ✓/✗ status for each variable
- Masked values (for security)
- Warnings if values look incorrect
- Next steps

### Method 2: Command Line

**Windows (PowerShell):**
```powershell
# Check if set (shows value - be careful!)
echo $env:QUIZ_SECRET
echo $env:OPENAI_API_KEY

# Check if set (just true/false)
if ($env:QUIZ_SECRET) { Write-Host "QUIZ_SECRET is set" } else { Write-Host "QUIZ_SECRET is NOT set" }
```

**Linux/Mac:**
```bash
# Check if set (shows value - be careful!)
echo $QUIZ_SECRET
echo $OPENAI_API_KEY

# Check if set (just true/false)
[ -n "$QUIZ_SECRET" ] && echo "QUIZ_SECRET is set" || echo "QUIZ_SECRET is NOT set"
[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_API_KEY is set" || echo "OPENAI_API_KEY is NOT set"
```

### Method 3: Python Script

**Quick check:**
```python
import os
print("QUIZ_SECRET:", "✓ Set" if os.getenv("QUIZ_SECRET") else "✗ Not set")
print("OPENAI_API_KEY:", "✓ Set" if os.getenv("OPENAI_API_KEY") else "✗ Not set (optional)")
```

**Detailed check:**
```python
import os

quiz_secret = os.getenv("QUIZ_SECRET")
openai_key = os.getenv("OPENAI_API_KEY")

if quiz_secret:
    print(f"✓ QUIZ_SECRET: Set (length: {len(quiz_secret)})")
else:
    print("✗ QUIZ_SECRET: NOT SET")

if openai_key:
    print(f"✓ OPENAI_API_KEY: Set (starts with: {openai_key[:3]})")
else:
    print("✗ OPENAI_API_KEY: NOT SET (optional)")
```

### Method 4: Test the API

Start the server and test:

```bash
# Start server
python -m app.main

# In another terminal, test health endpoint
curl http://localhost:8000/health

# Test with invalid secret (should return 403)
curl -X POST http://localhost:8000/solve \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","secret":"wrong","url":"https://example.com"}'
```

If you get `{"error":"forbidden"}`, the secret validation is working!

---

## Security Best Practices

1. **Never commit secrets to Git:**
   - Add `.env` to `.gitignore` (already included)
   - Use environment variables or secrets management

2. **Use strong secrets:**
   - `QUIZ_SECRET`: Use a long random string (32+ characters)
   - Generate with: `python -c "import secrets; print(secrets.token_urlsafe(32))"`

3. **Rotate keys regularly:**
   - Change `QUIZ_SECRET` periodically
   - Regenerate OpenAI API keys if compromised

4. **For production:**
   - Use secret management services (AWS Secrets Manager, Azure Key Vault, etc.)
   - Never hardcode secrets in code
   - Use different secrets for dev/staging/production

---

## Quick Start Script

Create `setup_env.sh` (Linux/Mac) or `setup_env.ps1` (Windows):

**setup_env.sh:**
```bash
#!/bin/bash
export QUIZ_SECRET="your_secret_key_here"
export OPENAI_API_KEY="sk-your-openai-api-key-here"
python -m app.main
```

**setup_env.ps1:**
```powershell
$env:QUIZ_SECRET = "your_secret_key_here"
$env:OPENAI_API_KEY = "sk-your-openai-api-key-here"
python -m app.main
```

---

## Troubleshooting

### Variable not found?
- Restart your terminal/IDE after setting variables
- Check spelling (case-sensitive)
- Verify with `echo $VARIABLE_NAME` or `echo $env:VARIABLE_NAME`

### HF Spaces not picking up variables?
- Ensure variables are saved in Settings
- Check Space logs for errors
- Rebuild the Space manually if needed

### Docker not using variables?
- Check `docker-compose.yml` syntax
- Use `docker run -e` for single container
- Verify with `docker exec container env`

---

## Need Help?

If you encounter issues:
1. Check the application logs
2. Verify variable names match exactly
3. Ensure no extra spaces in values
4. Test with a simple `print(os.getenv("VAR"))` in Python