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:

   # .env.local is already created for you!
   # Just add your Steam API key
   

2. Add your Steam API Key to .env.local:

   STEAM_API_KEY=your_actual_steam_api_key_here
   

   Get your key from: https://steamcommunity.com/dev/apikey

3. Start the server:

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

# 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

MONGODB_URI=mongodb://localhost:27017/turbotrades

Server

NODE_ENV=development          # or 'production'
PORT=3000
HOST=0.0.0.0

Steam OAuth

STEAM_API_KEY=your_key_here
STEAM_REALM=http://localhost:3000
STEAM_RETURN_URL=http://localhost:3000/api/auth/steam/return

CORS & Cookies

CORS_ORIGIN=http://localhost:5173
COOKIE_DOMAIN=localhost
COOKIE_SECURE=false           # true for production
COOKIE_SAME_SITE=lax

JWT & Sessions

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

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:

MONGODB_URI=mongodb://localhost:27017/turbotrades

"CORS Error" in Browser

Cause: Backend and frontend origins don't match.

Fix: Check .env.local:

CORS_ORIGIN=http://localhost:5173

"Steam authentication failed"

Cause: Missing or invalid Steam API key.

Fix: Add your key to .env.local:

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
• Steam Web API documentation
• MongoDB Connection Strings

🤝 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