Environment Configuration Guide

📚 Advanced Getting Started | For users configuring custom environments or preparing for deployment

Overview

Loan Defenders uses environment-based configuration to support multiple deployment scenarios without code changes. This guide explains how to configure the application for different environments.

New to Loan Defenders?

If you're just getting started, check out Local Development first. This guide is for advanced configuration scenarios.

Configuration Hierarchy

The application follows a clear configuration hierarchy:

1. Environment Variables (highest priority)
2. .env files (development defaults)
3. Code defaults (fallback)

This means you can override any configuration by setting environment variables, making deployment flexible without code changes.

Quick Reference

Configuration Files

File	Purpose	Environment
`.env` (root)	API and MCP server config	Local development
`apps/ui/.env`	UI-specific config	Local development
`.env.example`	Configuration documentation	Template for all environments
`docker-compose.yml`	Container configuration	Docker local/production
CI/CD secrets	Production URLs	Azure deployment

Key Configuration Variables

Variable	Purpose	Example Values
`VITE_PORT`	UI dev server port	`5173`, `3000`
`VITE_API_BASE_URL`	Backend API endpoint	`http://localhost:8000`, `https://api.azure.com`
`MCP_*_URL`	MCP server endpoints	`http://localhost:8010/mcp`
`APP_CORS_ORIGINS`	Allowed UI origins	`http://localhost:5173`

Environment-Specific Configuration

Local Development (Default)

When to use: Daily development on your machine

Configuration:

# .env (repository root)
MCP_APPLICATION_VERIFICATION_URL=http://localhost:8010/mcp
MCP_DOCUMENT_PROCESSING_URL=http://localhost:8011/mcp
MCP_FINANCIAL_CALCULATIONS_URL=http://localhost:8012/mcp

# apps/ui/.env
VITE_PORT=5173
VITE_API_BASE_URL=http://localhost:8000

Start services:

./scripts/start_local_dev.sh

Access: - UI: http://localhost:5173 - API: http://localhost:8000 - MCP Servers: 8010, 8011, 8012

Docker Compose (Local)

When to use: Testing containerized deployment on your machine

Configuration:

# docker-compose.yml
ui:
  build:
    args:
      # Uses host machine's API
      VITE_API_BASE_URL: http://localhost:8000

api:
  environment:
    # API runs in container, accesses other containers by service name
    MCP_APP_VERIFICATION_URL: "http://mcp-app-verification:8010/mcp"
    MCP_DOC_PROCESSING_URL: "http://mcp-doc-processing:8011/mcp"
    MCP_FINANCIAL_CALC_URL: "http://mcp-financial-calc:8012/mcp"

Start services:

docker-compose up --build

Access: - UI: http://localhost:8080 (container port 8080 mapped to host) - API: http://localhost:8000

Docker Compose (Production-like)

When to use: Testing production configuration locally before deployment

Override API URL for container networking:

# Build with container network API URL
VITE_API_BASE_URL=http://api:8000 docker-compose up --build

Or create .env.docker file:

# .env.docker
VITE_API_BASE_URL=http://api:8000
APP_CORS_ORIGINS=http://localhost:8080

Use it:

docker-compose --env-file .env.docker up --build

Azure Container Apps (Production)

When to use: Production deployment to Azure

CI/CD Configuration (GitHub Actions):

# .github/workflows/deploy.yml
- name: Build UI Image
  run: |
    docker build \
      --build-arg VITE_API_BASE_URL=${{ secrets.AZURE_API_URL }} \
      --build-arg VITE_APP_VERSION=${{ github.sha }} \
      -t ${{ secrets.ACR_URL }}/loan-defenders-ui:${{ github.sha }} \
      ./apps/ui

- name: Build API Image
  run: |
    docker build \
      -t ${{ secrets.ACR_URL }}/loan-defenders-api:${{ github.sha }} \
      ./apps/api

Azure Container Apps Environment Variables:

# Set in Azure Portal or via Azure CLI
az containerapp update \
  --name loan-defenders-api \
  --resource-group loan-defenders-rg \
  --set-env-vars \
    "MCP_APP_VERIFICATION_URL=http://mcp-app-verification.internal.env.azurecontainerapps.io/mcp" \
    "APP_CORS_ORIGINS=https://loan-defenders.azurestaticapps.net"

Configuration Scenarios

Scenario 1: Change UI Port

Problem: Port 5173 is already in use

Solution:

# Option 1: Temporary override
VITE_PORT=3000 npm run dev

# Option 2: Update .env file
# apps/ui/.env
VITE_PORT=3000

Scenario 2: Point to Remote API

Problem: Test UI against deployed API

Solution:

# Update apps/ui/.env
VITE_API_BASE_URL=https://loan-defenders-api-staging.azurecontainerapps.io

# Restart UI
npm run dev

Scenario 3: Custom MCP Server URLs

Problem: MCP servers running on non-standard ports

Solution:

# Update .env (root)
MCP_APPLICATION_VERIFICATION_URL=http://localhost:9010/mcp
MCP_DOCUMENT_PROCESSING_URL=http://localhost:9011/mcp
MCP_FINANCIAL_CALCULATIONS_URL=http://localhost:9012/mcp

# Restart services
./scripts/stop_local_dev.sh
./scripts/start_local_dev.sh

Problem: Team shares deployed MCP servers to save resources

Solution:

# Each developer's .env points to shared services
MCP_APPLICATION_VERIFICATION_URL=http://shared-dev-server:8010/mcp
MCP_DOCUMENT_PROCESSING_URL=http://shared-dev-server:8011/mcp
MCP_FINANCIAL_CALCULATIONS_URL=http://shared-dev-server:8012/mcp

# Update CORS on API to allow all developers
APP_CORS_ORIGINS=http://localhost:5173,http://dev-machine-1:5173,http://dev-machine-2:5173

Environment Variable Reference

UI Configuration

Variable	Required	Default	Description
`VITE_PORT`	No	`5173`	Development server port
`VITE_API_BASE_URL`	Yes	`http://localhost:8000`	Backend API endpoint
`VITE_API_TIMEOUT`	No	`30000`	API request timeout (ms)
`VITE_API_RETRIES`	No	`3`	API retry attempts
`VITE_APP_VERSION`	No	`1.0.0`	Application version
`VITE_ENABLE_ANALYTICS`	No	`false`	Enable analytics tracking

API Configuration

Variable	Required	Default	Description
`APP_CORS_ORIGINS`	Yes	-	Comma-separated allowed origins
`APP_DEBUG`	No	`false`	Enable debug mode
`APP_LOG_LEVEL`	No	`INFO`	Logging level
`AZURE_AI_PROJECT_ENDPOINT`	Yes	-	Azure AI Foundry endpoint
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	Yes	-	Model deployment name

MCP Server Configuration

Variable	Required	Default	Description
`MCP_SERVER_HOST`	No	`0.0.0.0`	Server bind host
`MCP_APPLICATION_VERIFICATION_PORT`	No	`8010`	App verification port
`MCP_DOCUMENT_PROCESSING_PORT`	No	`8011`	Doc processing port
`MCP_FINANCIAL_CALCULATIONS_PORT`	No	`8012`	Financial calc port
`MCP_APPLICATION_VERIFICATION_URL`	Yes	-	Full URL for API to connect
`MCP_DOCUMENT_PROCESSING_URL`	Yes	-	Full URL for API to connect
`MCP_FINANCIAL_CALCULATIONS_URL`	Yes	-	Full URL for API to connect

Best Practices

✅ DO

Use .env.example as template

cp .env.example .env
cp apps/ui/.env.example apps/ui/.env

Keep secrets in CI/CD only
Production URLs in GitHub Secrets
Azure credentials in Azure Key Vault
Never commit sensitive values

Document environment-specific values

# .env.production.example
VITE_API_BASE_URL=https://api.yourdomain.com  # Production API
APP_CORS_ORIGINS=https://yourdomain.com       # Production UI

Use descriptive comments

# Backend API endpoint
# Local: http://localhost:8000
# Staging: https://api-staging.azure.com
# Production: https://api.azure.com
VITE_API_BASE_URL=http://localhost:8000

Validate configuration on startup

# Check required environment variables exist
./scripts/validate_env.sh

❌ DON'T

Don't hardcode values in code

// ❌ Bad
const apiUrl = 'http://localhost:8000';

// ✅ Good
const apiUrl = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000';

Don't commit .env files
.env is in .gitignore
Only commit .env.example
Don't use production URLs locally
Keep local development isolated
Use staging for integration testing

Don't mix environment configurations

# ❌ Bad - mixing local and production
VITE_API_BASE_URL=http://localhost:8000
MCP_APP_VERIFICATION_URL=https://prod-mcp.azure.com/mcp

Troubleshooting

Issue: Configuration not applying

Check: 1. Environment variable name is correct (case-sensitive) 2. Restart the service after changing .env 3. For Vite, env vars must start with VITE_ 4. Docker requires rebuild: docker-compose up --build

Issue: CORS errors in browser

Solution:

# Update API CORS to include UI origin
# .env
APP_CORS_ORIGINS="http://localhost:5173,http://localhost:8080"

Issue: MCP servers unreachable

Check: 1. MCP server URLs are correct 2. Ports are not blocked by firewall 3. Services are running: ./scripts/status_local_dev.sh 4. Health check passes: curl http://localhost:8010/health

Issue: Docker build failing

Solution:

# Check build args are set
docker-compose config | grep VITE_API_BASE_URL

# Rebuild with explicit args
docker build \
  --build-arg VITE_API_BASE_URL=http://localhost:8000 \
  -t loan-defenders-ui \
  ./apps/ui

Next Steps

Testing Your Configuration: Troubleshooting Guide
Docker Deployment: Docker Development
Azure Deployment: Azure Deployment Overview
CI/CD Setup: See .github/workflows/ for pipeline examples

Environment Configuration Guide

Overview

Configuration Hierarchy

Quick Reference

Configuration Files

Key Configuration Variables

Environment-Specific Configuration

Local Development (Default)

Docker Compose (Local)

Docker Compose (Production-like)

Azure Container Apps (Production)

Configuration Scenarios

Scenario 1: Change UI Port

Scenario 2: Point to Remote API

Scenario 3: Custom MCP Server URLs

Scenario 4: Multiple Developers Sharing Services

Environment Variable Reference

UI Configuration

API Configuration

MCP Server Configuration

Best Practices

✅ DO

❌ DON'T

Troubleshooting

Issue: Configuration not applying

Issue: CORS errors in browser

Issue: MCP servers unreachable

Issue: Docker build failing

Next Steps

Related Documentation