roa2web-service-auto/backend/ENV-SETUP.md

# Environment Configuration Guide

## Overview

The unified backend uses environment-specific configuration files that are automatically loaded by startup scripts.

**SECURITY**: All `.env*` files (except `.env*.example`) contain real credentials and are **NEVER committed to git**.

## File Structure

```
backend/
├── .env.prod.example    # Production template (COMMITTED - no credentials)
├── .env.test.example   # Test template (COMMITTED - no credentials)
├── .env.prod.example   # Production template (COMMITTED - no credentials)
├── .env.example        # Generic template (COMMITTED)
├── .env.prod            # Production config (IGNORED - real credentials)
├── .env.test           # Test config (IGNORED - real credentials)
├── .env.prod           # Production config (IGNORED - real credentials)
└── .env                # Active config (IGNORED - auto-generated)
```

## First-Time Setup

### Production
```bash
# 1. Copy template
cp backend/.env.prod.example backend/.env.prod

# 2. Edit with your credentials
vim backend/.env.prod

# 3. Fill in:
#    - ORACLE_PASSWORD
#    - JWT_SECRET_KEY (generate with: python3 -c "import secrets; print(secrets.token_urlsafe(32))")
#    - AUTH_SESSION_SECRET (generate with: python3 -c "import secrets; print(secrets.token_urlsafe(32))")
#    - TELEGRAM_BOT_TOKEN (from @BotFather)
#    - SMTP_PASSWORD

# 4. Start
./start.sh prod
```

### Test
```bash
# Same process with .env.test
cp backend/.env.test.example backend/.env.test
vim backend/.env.test
# Fill in TEST credentials (separate from dev!)
./start.sh test
```

### Production
```bash
# Same process with .env.prod
cp backend/.env.prod.example backend/.env.prod
vim backend/.env.prod
# Fill in PRODUCTION credentials (generate NEW secrets!)
./start-backend.sh start
```

## How It Works

### Production
```bash
./start.sh prod       # Checks for .env.prod → copies to .env → starts backend
```

### Test
```bash
./start.sh test      # Checks for .env.test → copies to .env → starts backend
```

### Production
```bash
# Manual setup (one-time)
cp .env.prod.example .env.prod
vim .env.prod        # Fill in credentials
# Then start
./start-backend.sh start
```

## Important Rules

### ✅ DO
- Copy `.env.*.example` to `.env.*` and fill in real credentials
- Edit `.env.prod` for production changes
- Edit `.env.test` for test environment changes
- Edit `.env.prod` for production
- Generate **new** secrets for each environment
- Keep `.env.prod`, `.env.test`, `.env.prod` **local only** (never commit!)

### ❌ DON'T
- Don't commit `.env`, `.env.prod`, `.env.test`, or `.env.prod` (they're in .gitignore)
- Don't manually edit `.env` (it's auto-generated!)
- Don't use same secrets across environments
- Don't share credentials via git (use secure channels)
- Don't put real credentials in `.env*.example` files

## Environment Differences

| Setting | .env.prod | .env.test | .env.prod |
|---------|----------|-----------|-----------|
| Oracle SID | `ROA` | `roa` | `ROA` |
| JWT Expire | 30 min | 480 min | 30 min |
| DEBUG | `true` | `true` | `false` |
| Cache DB | `roa2web_cache.db` | `roa2web_cache_test.db` | `roa2web_cache_prod.db` |
| Receipts DB | `receipts_dev.db` | `receipts_test.db` | `receipts_prod.db` |
| Telegram DB | `telegram.db` | `telegram_test.db` | `telegram_prod.db` |

## Security Notes

### Template Files (.env.*.example)
These contain **placeholders only**:
- ✅ Safe to commit to git
- ✅ Shared across team
- ✅ No real credentials
- 📖 Used as reference for first-time setup

### Actual Config Files (.env.prod, .env.test, .env.prod)
These contain **real credentials**:
- ❌ **NEVER commit to git** (in .gitignore)
- ❌ Never share via email/chat
- ✅ Keep local only
- ✅ Generate unique secrets per environment
- 🔐 Share securely if needed (encrypted vault, 1Password, etc.)

### Active Config (.env)
This is **auto-generated** and **ignored by git**:
- ❌ Never commit to git
- 🔄 Auto-overwritten by startup scripts
- 📝 Edit source files (.env.prod, .env.test) instead

## Generating Secrets

For `JWT_SECRET_KEY` and `AUTH_SESSION_SECRET`:
```bash
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```

Generate **different** secrets for dev, test, and production!

## Quick Reference

### First Time Setup
```bash
# 1. Copy template
cp backend/.env.prod.example backend/.env.prod

# 2. Fill credentials
vim backend/.env.prod

# 3. Start
./start.sh prod
```

### Changing Configuration
```bash
# 1. Edit source file
vim backend/.env.prod

# 2. Restart to apply
./start.sh prod
```

### Production Deployment
```bash
# 1. Copy template
cp backend/.env.prod.example backend/.env.prod

# 2. Fill in PRODUCTION values
vim backend/.env.prod

# 3. Generate NEW secrets
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# 4. Start backend
./start-backend.sh start
```

## Troubleshooting

### "Wrong database" error
Check that you're using the correct startup script:
- Production: `./start.sh prod` (uses `.env.prod`)
- Test: `./start.sh test` (uses `.env.test`)

### ".env.prod not found" error
First-time setup required:
```bash
cp backend/.env.prod.example backend/.env.prod
vim backend/.env.prod  # Fill in your credentials
```

### Changes not taking effect
The `.env` file is regenerated on each start. Edit the source file (`.env.prod` or `.env.test`) instead.

### Checking what will be committed
```bash
git status backend/.env*
# Should show:
#   modified: .env.prod.example (if you changed template)
#   nothing else!
```

## Team Sharing

**Templates only** are committed to git:
- Share configuration structure via `.env*.example`
- Each developer creates their own `.env.prod` from template
- Never commit actual credentials
- Use secure channels for sharing sensitive values (1Password, encrypted vault, etc.)