Skip to content

Environment Guide

Quick guide to SPOT Platform environments.

Three Environments

SPOT uses APP_ENV to control which environment is active:

Environment Purpose Default
prod Production deployment Yes
dev Development with hot reload No
test Isolated testing No

Quick Reference

# Production (default)
make service:start

# Development (hot reload)
APP_ENV=dev make service:start

# Test (automatic for test commands)
make test:integration

Switching Environments

# Development mode
APP_ENV=dev make service:start

# Production mode (default)
make service:start

Method 2: Environment Variable

# Override for single command
APP_ENV=dev make service:start

Method 3: Persistent Change in .env

# Edit .env
vim .env
# Change: APP_ENV=prod
# To:     APP_ENV=dev

# Restart to apply
make service:restart

Important: Changing APP_ENV in .env requires a restart.

Environment Differences

Production (prod)

  • Optimized for: Stability, performance, security
  • Hot reload: Disabled
  • Debug tools: Disabled
  • Dev dependencies: Not installed
  • Compose profiles: None (base services only)

Development (dev)

  • Optimized for: Developer productivity
  • Hot reload: Enabled (changes auto-reload)
  • Debug tools: Adminer (:8080), MailHog (:8025), devtools
  • Dev dependencies: Installed
  • Volume mounts: Read-write for source code
  • Compose profiles: --profile dev

Test (test)

  • Optimized for: Isolated testing
  • Mock analyzers: Included (analyzer-mock-nlp, analyzer-mock-llm)
  • Log level: WARNING (reduced verbosity)
  • Compose profiles: --profile dev --profile test

Precedence

The system determines the active environment using this order (highest to lowest):

  1. Command-line flag: APP_ENV=dev make service:start
  2. Environment variable: APP_ENV=dev
  3. .env file: APP_ENV=prod
  4. Default: prod

Common Workflows

Development Workflow

# Start in dev mode
APP_ENV=dev make service:start

# Make code changes (auto-reload active)

# View logs
make service:logs

# When done
make service:stop

Testing Workflow

# Run tests (automatically uses APP_ENV=test)
make test:unit
make test:integration

# No manual environment switching needed

Production Deployment

# Ensure .env has APP_ENV=prod (or remove the line for default)
grep "APP_ENV" .env

# Start production services
make service:start

# Check status
make service:status

Safety Features

Test Environment Enforcement

Integration tests will fail if APP_ENV != test:

# tests/conftest.py enforces this
if app_env != "test":
    raise RuntimeError("Integration tests must run in test environment")

This prevents accidental execution against development or production databases.

Troubleshooting

Services Started in Wrong Environment

# Stop services
make service:stop

# Verify .env
cat .env | grep APP_ENV

# Start with correct environment
APP_ENV=dev make service:start  # or without --dev for prod

Can't Tell Which Environment is Running

# Check status (shows environment)
make service:status

Environment Change Not Applied

# Restart required after changing .env
make service:restart

Best Practices

  1. Use --dev flag for development

  2. Clearer and more explicit than environment variables

  3. Use test commands for testing

  4. make test:unit sets APP_ENV=test automatically

  5. Default to prod for safety

  6. Production is the default, explicitly opt into dev mode

  7. Restart after changing .env

  8. Docker Compose needs to reload with new environment