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

# 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-prod.sh

Test

# 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-test.sh

Production

# 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

./start-prod.sh       # Checks for .env.prod → copies to .env → starts backend

Test

./start-test.sh      # Checks for .env.test → copies to .env → starts backend

Production

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

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Generate different secrets for dev, test, and production!

Quick Reference

First Time Setup

# 1. Copy template
cp backend/.env.prod.example backend/.env.prod

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

# 3. Start
./start-prod.sh

Changing Configuration

# 1. Edit source file
vim backend/.env.prod

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

Production Deployment

# 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-prod.sh (uses .env.prod)
• Test: ./start-test.sh (uses .env.test)

".env.prod not found" error

First-time setup required:

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

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