Environments Configuration

Define connections to external environments like staging and production.

Basic Environment


environments:
  staging:
    description: Staging environment
    urls:
      api: https://api.staging.example.com

Full Configuration


environments:
  staging:
    description: Staging environment for testing
    urls:
      api: https://api.staging.example.com
      admin: https://admin.staging.example.com
      web: https://staging.example.com
 
    env:
      MONGODB_URI: ${STAGING_MONGODB_URI}
      REDIS_URL: ${STAGING_REDIS_URL}
      API_KEY: ${STAGING_API_KEY}
 
  production:
    description: Production environment (read-only)
    urls:
      api: https://api.example.com
      admin: https://admin.example.com
 
    env:
      MONGODB_URI: ${PROD_MONGODB_URI}
 
    safety:
      read_only: true
      require_confirmation: true
      allowed_operations:
        - read
        - list

Environment URLs

Map service names to their URLs:


environments:
  staging:
    urls:
      # API services
      api: https://api.staging.example.com
      auth: https://auth.staging.example.com
      gateway: https://gateway.staging.example.com
 
      # Frontend apps
      web: https://staging.example.com
      admin: https://admin.staging.example.com
 
      # Infrastructure (if externally accessible)
      mongodb: mongodb+srv://staging-cluster.mongodb.net
      redis: redis://staging-redis.example.com:6379

Using Environment Variables

Reference secrets from .env.genbox:


environments:
  staging:
    env:
      MONGODB_URI: ${STAGING_MONGODB_URI}
      REDIS_URL: ${STAGING_REDIS_URL}
      AWS_ACCESS_KEY: ${STAGING_AWS_KEY}

.env.genbox:


STAGING_MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/staging
STAGING_REDIS_URL=redis://user:pass@redis.example.com:6379
STAGING_AWS_KEY=AKIAIOSFODNN7EXAMPLE

Safety Controls

Protect sensitive environments:


environments:
  production:
    description: Production - BE CAREFUL
    urls:
      api: https://api.example.com
 
    safety:
      # Mark as read-only
      read_only: true
 
      # Require confirmation before any operation
      require_confirmation: true
 
      # Only allow specific operations
      allowed_operations:
        - read
        - list
        - export
 
      # Block dangerous operations
      blocked_operations:
        - write
        - delete
        - truncate

Using Environments in Profiles

Connect to environments via profiles:


profiles:
  quick:
    description: Frontend with staging backend
    apps:
      - frontend
    default_connection: staging       # Use staging for all dependencies
 
  hybrid:
    description: Local API, staging external
    apps:
      - frontend
      - backend
    connections:
      frontend:
        api: local                    # Local API
      backend:
        mongodb: local                # Local database
        external-api: staging         # Staging external API
        analytics: production         # Production analytics (read-only)

Database Sync from Environments

Copy data from external environments:


profiles:
  with-data:
    database:
      mode: copy
      source: staging                 # Copy from staging environment
 
  prod-debug:
    database:
      mode: copy
      source: production              # Copy from production

Multiple Environment Sets

Organize environments by purpose:


environments:
  # Development/Testing
  dev:
    urls:
      api: https://api.dev.example.com
 
  # Staging
  staging:
    urls:
      api: https://api.staging.example.com
 
  # Production (by region)
  production-us:
    urls:
      api: https://api.us.example.com
    safety:
      read_only: true
 
  production-eu:
    urls:
      api: https://api.eu.example.com
    safety:
      read_only: true

Validation

Genbox validates environment references:


gb validate


Validating configuration...

Environment references:
  ✓ staging.mongodb.url resolved
  ✓ staging.api.url resolved
  ⚠ production.mongodb.url contains ${PROD_MONGODB_URI}
    PROD_MONGODB_URI not found in .env.genbox

    This will fail at runtime unless the variable is set.

Best Practices

Use descriptive names: staging, production-us, not env1
Protect production: Always use safety controls
Use environment variables: Never hardcode secrets
Document URLs: Add descriptions for clarity
Validate regularly: Run gb validate before using