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:

$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):

[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:

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:

pip install python-dotenv

3. Update app/main.py to load .env file (add at the top):

from dotenv import load_dotenv
load_dotenv()

---

Method 2: Linux/Mac (Bash)

Temporary (Current Session Only)

Open terminal and run:

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:

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:

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:

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:

docker-compose up

---

Verification

Method 1: Using the Check Script (Easiest)

Run the included verification script:

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):

# 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:

# 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:

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:

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:

# 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:

#!/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:

$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