Skip to main content

Environment Configurations

Overview​

BookWish runs in three environments: Development, Staging, and Production. Each has different configurations optimized for its purpose.

Environment Overview​

EnvironmentPurposeURLDatabaseUpdates
DevelopmentLocal developmentlocalhostLocal PostgreSQLManual
StagingTesting & QAstaging.bookwish.ioStaging DBAuto on merge to main
ProductionLive usersbookwish.ioProduction DBManual release

Development Environment​

Purpose​

  • Local development and testing
  • Fast iteration and debugging
  • No risk to production data

Configuration​

Backend (backend/.env.development)

NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://localhost:5432/bookwish_dev
REDIS_URL=redis://localhost:6379
API_BASE_URL=http://localhost:3000

# Debug settings
LOG_LEVEL=debug
ENABLE_QUERY_LOGGING=true
CORS_ORIGIN=http://localhost:8080

# External services (use test keys)
STRIPE_SECRET_KEY=sk_test_...
SQUARE_ACCESS_TOKEN=sandbox-...
AWS_S3_BUCKET=bookwish-dev

Flutter App (app/.env.development)

API_BASE_URL=http://localhost:3000
ENVIRONMENT=development
ENABLE_LOGGING=true

Setup​

# Backend
cd backend
npm install
cp .env.example .env.development
npm run db:migrate
npm run db:seed
npm run dev

# App
cd app
flutter pub get
flutter run

Features​

  • Hot reload enabled
  • Detailed error messages
  • SQL query logging
  • Mock payment processing
  • Test user accounts

Staging Environment​

Purpose​

  • Pre-production testing
  • QA validation
  • Client demos
  • Integration testing

Configuration​

Backend

NODE_ENV=staging
PORT=3000
DATABASE_URL=${{ secrets.STAGING_DATABASE_URL }}
REDIS_URL=${{ secrets.STAGING_REDIS_URL }}
API_BASE_URL=https://staging-api.bookwish.io

# Moderate logging
LOG_LEVEL=info
ENABLE_QUERY_LOGGING=false
CORS_ORIGIN=https://staging.bookwish.io

# External services (use test keys)
STRIPE_SECRET_KEY=sk_test_...
SQUARE_ACCESS_TOKEN=sandbox-...
AWS_S3_BUCKET=bookwish-staging

Flutter Web

API_BASE_URL=https://staging-api.bookwish.io
ENVIRONMENT=staging
ENABLE_LOGGING=true

Deployment​

Automatic on merge to main:

git push origin main
# Triggers GitHub Actions workflow
# Deploys to staging automatically

Access​

Data​

  • Reset weekly
  • Seeded with test data
  • Safe for testing destructive operations

Production Environment​

Purpose​

  • Live application for real users
  • Maximum stability and performance
  • Data integrity and security

Configuration​

Backend

NODE_ENV=production
PORT=3000
DATABASE_URL=${{ secrets.PRODUCTION_DATABASE_URL }}
REDIS_URL=${{ secrets.PRODUCTION_REDIS_URL }}
API_BASE_URL=https://api.bookwish.io

# Production logging
LOG_LEVEL=warn
ENABLE_QUERY_LOGGING=false
CORS_ORIGIN=https://bookwish.io

# External services (use production keys)
STRIPE_SECRET_KEY=${{ secrets.STRIPE_PRODUCTION_KEY }}
SQUARE_ACCESS_TOKEN=${{ secrets.SQUARE_PRODUCTION_TOKEN }}
AWS_S3_BUCKET=bookwish-production

# Security
RATE_LIMIT_MAX=100
SESSION_SECRET=${{ secrets.SESSION_SECRET }}
JWT_SECRET=${{ secrets.JWT_SECRET }}

Flutter Web

API_BASE_URL=https://api.bookwish.io
ENVIRONMENT=production
ENABLE_LOGGING=false

Deployment​

Manual release process:

npm run release
# Creates version tag
# Triggers production deployment

See Release Process for details.

Access​

Monitoring​

  • Error tracking enabled
  • Performance monitoring
  • Uptime alerts
  • Automated backups

Environment Variables​

Backend Variables​

VariableDevStagingProductionDescription
NODE_ENVdevelopmentstagingproductionEnvironment name
DATABASE_URLLocalStaging DBProduction DBPostgreSQL connection
REDIS_URLLocalStaging RedisProduction RedisRedis connection
LOG_LEVELdebuginfowarnLogging verbosity
STRIPE_SECRET_KEYTest keyTest keyLive keyStripe API key
AWS_S3_BUCKETdev bucketstaging bucketprod bucketS3 bucket name

Frontend Variables​

VariableDevStagingProductionDescription
API_BASE_URLlocalhost:3000staging-apiapiBackend API URL
ENVIRONMENTdevelopmentstagingproductionEnvironment name
ENABLE_LOGGINGtruetruefalseDebug logging

Database Configuration​

Development Database​

-- Local PostgreSQL
Database: bookwish_dev
User: bookwish
Password: (local only)

-- Auto-seeded with:
- Test users
- Sample books
- Test stores
- Demo wishlists

Staging Database​

-- Managed PostgreSQL (e.g., Supabase, Railway)
- Separate from production
- Reset weekly
- Test data seeded
- Safe for destructive testing

Production Database​

-- Managed PostgreSQL with:
- High availability
- Automated backups (daily)
- Point-in-time recovery
- Read replicas
- Connection pooling

Redis Configuration​

Development​

# Local Redis
redis://localhost:6379
# No password
# No persistence required

Staging​

# Managed Redis
redis://staging-redis.bookwish.io:6379
# Password protected
# Persistence enabled

Production​

# Managed Redis with:
- High availability
- Automatic failover
- Persistence enabled
- Regular backups

File Storage (S3/CDN)​

Development​

Bucket: bookwish-dev
Region: us-east-1
Public access: Enabled (for testing)

Staging​

Bucket: bookwish-staging
Region: us-east-1
CDN: staging-cdn.bookwish.io
Public access: Controlled

Production​

Bucket: bookwish-production
Region: us-east-1
CDN: cdn.bookwish.io
Public access: Controlled
Backup: Enabled
Versioning: Enabled

External Services​

Payment Processing​

Development:

  • Stripe: Test mode
  • Square: Sandbox environment
  • Mock webhooks

Staging:

  • Stripe: Test mode
  • Square: Sandbox environment
  • Real webhooks to staging URL

Production:

  • Stripe: Live mode
  • Square: Production environment
  • Real webhooks to production URL

Email Service​

Development:

  • Mailhog or console output
  • No real emails sent

Staging:

  • SendGrid/SES test credentials
  • Emails to test addresses only

Production:

  • SendGrid/SES production credentials
  • Real emails to users

Switching Environments​

Backend​

# Development
npm run dev

# Staging
npm run start:staging

# Production
npm run start:production

Flutter​

# Development
flutter run --dart-define=ENVIRONMENT=development

# Staging
flutter run --dart-define=ENVIRONMENT=staging

# Production
flutter build web --release --dart-define=ENVIRONMENT=production

Environment-Specific Features​

Development Only​

  • Hot reload
  • Detailed stack traces
  • SQL query logging
  • Mock data generators
  • Development tools enabled

Staging Only​

  • Test data reset scripts
  • Demo user accounts
  • QA testing tools
  • Non-production analytics

Production Only​

  • Error tracking (Sentry)
  • Performance monitoring (DataDog)
  • Analytics (Google Analytics)
  • Rate limiting (strict)
  • CDN caching

Security Considerations​

Development​

  • Use test API keys
  • Local database only
  • No sensitive data
  • CORS wide open for testing

Staging​

  • Test API keys only
  • Separate staging database
  • No production data
  • CORS restricted to staging domains

Production​

  • Live API keys secured
  • Encrypted database connections
  • Regular security audits
  • Strict CORS policies
  • Rate limiting enabled
  • DDoS protection

Troubleshooting​

Environment Variable Not Working​

# Check if variable is set
echo $VARIABLE_NAME

# Verify .env file is loaded
cat .env.development

# Check for typos in variable names
grep -r "VARIABLE_NAME" .

Wrong Environment Running​

# Check NODE_ENV
node -e "console.log(process.env.NODE_ENV)"

# Verify which .env file is loaded
node -e "console.log(require('dotenv').config())"

Database Connection Issues​

# Test database connection
psql $DATABASE_URL

# Check database exists
psql -l | grep bookwish

# Verify migrations are current
npm run db:migrate:status

Best Practices​

Do's​

✅ Use environment variables for all configuration ✅ Never commit .env files ✅ Keep development and production separated ✅ Test in staging before production ✅ Use different API keys per environment ✅ Document environment-specific behavior

Don'ts​

❌ Use production credentials in development ❌ Test destructive operations in production ❌ Share production database with staging ❌ Hard-code environment-specific values ❌ Skip staging deployments ❌ Use production data in development

References​