TurboTrades/ENV_SETUP.md

# Environment Variables Setup Guide

This guide explains how to manage environment variables for local development vs. production deployment.

## 📁 File Structure

```
TurboTrades/
├── .env              # Production/deployment settings (COMMITTED to git)
├── .env.local        # Local development overrides (NOT committed)
├── .env.example      # Template for reference
└── .env.tunnel       # Cloudflare tunnel settings (optional)
```

## 🔄 How It Works

The application loads environment variables in this order:

1. **`.env.local`** - Loaded first (highest priority)
2. **`.env`** - Loaded second (fallback values)

This means:
- Variables in `.env.local` **override** those in `.env`
- `.env.local` is in `.gitignore` and **never gets pushed** to git
- `.env` contains your production settings and **is committed** to git

## 🚀 Quick Setup

### For Local Development

1. **Copy the template:**
   ```bash
   # .env.local is already created for you!
   # Just add your Steam API key
   ```

2. **Add your Steam API Key to `.env.local`:**
   ```env
   STEAM_API_KEY=your_actual_steam_api_key_here
   ```
   
   Get your key from: https://steamcommunity.com/dev/apikey

3. **Start the server:**
   ```bash
   npm run dev
   ```
   
   The server will automatically use:
   - Local MongoDB (`mongodb://localhost:27017/turbotrades`)
   - Local frontend (`http://localhost:5173`)
   - No HTTPS required (`COOKIE_SECURE=false`)

### For Production/Deployment

Your `.env` file should contain production settings:
- Production MongoDB connection (MongoDB Atlas or remote server)
- Production domain for CORS
- Secure cookies enabled (`COOKIE_SECURE=true`)
- Production Steam return URL

**Never commit sensitive production credentials!** Use environment variables in your hosting platform instead.

## 🔧 Common Scenarios

### Scenario 1: Switching Between Local and Production MongoDB

**Problem:** You keep changing `MONGODB_URI` in `.env` and forgetting to change it back.

**Solution:** 
- Keep production MongoDB URI in `.env`
- Put local MongoDB URI in `.env.local`
- Never edit `.env` for local development!

```env
# .env (production - committed)
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/turbotrades

# .env.local (local dev - not committed)
MONGODB_URI=mongodb://localhost:27017/turbotrades
```

### Scenario 2: Testing with Cloudflare Tunnel

Use `.env.tunnel` for tunnel-specific settings:

```bash
# Copy tunnel settings
cp .env.tunnel .env.local

# Or manually edit .env.local with your tunnel URL
```

### Scenario 3: Team Development

**Each developer should:**
1. Keep their own `.env.local` (never commit it!)
2. Share the `.env` file with production-like defaults
3. Update `.env.example` when adding new variables

## 📝 Environment Variables Reference

### Database
```env
MONGODB_URI=mongodb://localhost:27017/turbotrades
```

### Server
```env
NODE_ENV=development          # or 'production'
PORT=3000
HOST=0.0.0.0
```

### Steam OAuth
```env
STEAM_API_KEY=your_key_here
STEAM_REALM=http://localhost:3000
STEAM_RETURN_URL=http://localhost:3000/api/auth/steam/return
```

### CORS & Cookies
```env
CORS_ORIGIN=http://localhost:5173
COOKIE_DOMAIN=localhost
COOKIE_SECURE=false           # true for production
COOKIE_SAME_SITE=lax
```

### JWT & Sessions
```env
JWT_ACCESS_SECRET=your-secret-here
JWT_REFRESH_SECRET=your-secret-here
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d
SESSION_SECRET=your-session-secret
```

### Rate Limiting
```env
RATE_LIMIT_MAX=100
RATE_LIMIT_TIMEWINDOW=60000
```

## ⚠️ Important Notes

### ✅ DO:
- Use `.env.local` for local development
- Commit `.env` with safe default values
- Keep sensitive keys in `.env.local`
- Update `.env.example` when adding new variables
- Use your hosting platform's environment variables for production secrets

### ❌ DON'T:
- Commit `.env.local` to git (it's in `.gitignore`)
- Store real API keys in `.env` (use placeholders)
- Edit `.env` for local development
- Share your `.env.local` file with others
- Commit sensitive credentials to the repository

## 🔍 Troubleshooting

### "Authentication failed" MongoDB Error
**Cause:** Using production MongoDB URI with credentials locally.

**Fix:** Make sure `.env.local` has:
```env
MONGODB_URI=mongodb://localhost:27017/turbotrades
```

### "CORS Error" in Browser
**Cause:** Backend and frontend origins don't match.

**Fix:** Check `.env.local`:
```env
CORS_ORIGIN=http://localhost:5173
```

### "Steam authentication failed"
**Cause:** Missing or invalid Steam API key.

**Fix:** Add your key to `.env.local`:
```env
STEAM_API_KEY=your_actual_key_from_steam
```
Get it here: https://steamcommunity.com/dev/apikey

### Changes not taking effect
**Cause:** Server not restarting or wrong file being edited.

**Fix:**
1. Make sure you're editing `.env.local` (not `.env`)
2. Restart the server: `npm run dev`
3. Clear `node_modules/.cache` if needed

## 📚 Additional Resources

- [dotenv documentation](https://github.com/motdotla/dotenv)
- [Steam Web API documentation](https://steamcommunity.com/dev)
- [MongoDB Connection Strings](https://www.mongodb.com/docs/manual/reference/connection-string/)

## 🤝 Contributing

When adding new environment variables:

1. Add it to `config/index.js` with a sensible default
2. Add it to `.env.example` with a placeholder value
3. Document it in this file
4. Update `API_ENDPOINTS.md` if it affects API behavior

---

**Last Updated:** 2024
**Maintainer:** TurboTrades Development Team