Environment Variables - Happy Habitat

Overview

Happy Habitat uses a hierarchical configuration system that supports multiple sources: appsettings.json, environment-specific files, and environment variables. This guide documents all available configuration options.

Configuration Hierarchy

Configuration sources are loaded in this order (later sources override earlier ones):

appsettings.json (base configuration)
appsettings.{Environment}.json (e.g., appsettings.Production.json)
Environment variables
Command-line arguments

Environment Variable Format

.NET configuration uses double underscores (__) to represent nested configuration:

# JSON format
"Database": {
  "RecreateOnStartup": false
}

# Environment variable format
Database__RecreateOnStartup=false

Backend Configuration

Required Settings

These settings are required in production. The application will fail to start if they are missing or invalid.

ConnectionStrings:DefaultConnection

Database connection string for SQL Server.

Type: String
Required: Yes
Default: None
Environment Variable: ConnectionStrings__DefaultConnection

Examples:

# SQL Authentication
ConnectionStrings__DefaultConnection="Server=sql.example.com;Database=HappyHabitat;User Id=dbuser;Password=SecureP@ss!;TrustServerCertificate=True;"

# Windows Authentication
ConnectionStrings__DefaultConnection="Server=(local);Database=HappyHabitat;Trusted_Connection=True;TrustServerCertificate=True;"

# Azure SQL
ConnectionStrings__DefaultConnection="Server=tcp:happyhabitat.database.windows.net,1433;Database=HappyHabitat;User ID=admin;Password=SecureP@ss!;Encrypt=True;"

See: Program.cs:70, appsettings.json:2-4

Jwt:Key

Secret key for signing JWT authentication tokens. Must be at least 32 characters.

Type: String
Required: Yes (production)
Default: YourSuperSecretKeyThatShouldBeAtLeast32CharactersLong! (development only)
Environment Variable: Jwt__Key
Validation:
- Cannot be empty in production (Program.cs:79-84)
- Cannot use default value in production (Program.cs:85-88)
- Minimum 32 characters recommended

Generate a secure key:

# Linux/Mac
openssl rand -base64 32

# PowerShell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))

Example:

Jwt__Key="8f3K9mP2nQ5rS7tV4wX6yZ1aB3cD5eF7gH9jK2lM4nP6qR8sT0uV2wX4yZ6aB8c"

See: Program.cs:74-90, appsettings.json:8-9, README.md:10

Cors:Origins

Semicolon-separated list of allowed frontend origins for CORS.

Type: String (semicolon-separated)
Required: Yes (production)
Default: http://localhost:4200;https://localhost:4200;http://localhost:5080;https://localhost:7177 (development only)
Environment Variable: Cors__Origins
Validation: Application fails to start if not configured in production (Program.cs:54-56)

Examples:

# Single origin
Cors__Origins="https://app.happyhabitat.com"

# Multiple origins
Cors__Origins="https://app.happyhabitat.com;https://admin.happyhabitat.com;https://www.happyhabitat.com"

# With ports
Cors__Origins="https://app.example.com:8443;https://admin.example.com:8443"

Important:

Do not include trailing slashes
Use exact protocol (http vs https)
Include port if non-standard

See: Program.cs:46-67, README.md:11

Database:RecreateOnStartup

Whether to drop and recreate the database on application startup.

Type: Boolean
Required: No
Default: false
Environment Variable: Database__RecreateOnStartup
Validation:
- Must be false in production (Program.cs:251-252)
- Application fails to start if true in production

NEVER set this to true in production. This will delete all data on every application restart.

Examples:

# Development only
Database__RecreateOnStartup=true

# Production (required)
Database__RecreateOnStartup=false

See: Program.cs:249-259, appsettings.json:5-7, README.md:12

Optional Settings

Jwt:Issuer

JWT token issuer identifier.

Type: String
Required: No
Default: HappyHabitat
Environment Variable: Jwt__Issuer

Example:

Jwt__Issuer="HappyHabitat"

See: Program.cs:91, appsettings.json:10

Jwt:Audience

JWT token audience identifier.

Type: String
Required: No
Default: HappyHabitatUsers
Environment Variable: Jwt__Audience

Example:

Jwt__Audience="HappyHabitatUsers"

See: Program.cs:92, appsettings.json:11

Logging:LogLevel:Default

Default minimum log level for application logging.

Type: String
Required: No
Default: Information
Allowed Values: Trace, Debug, Information, Warning, Error, Critical, None
Environment Variable: Logging__LogLevel__Default

Examples:

# Development
Logging__LogLevel__Default="Debug"

# Production
Logging__LogLevel__Default="Warning"

See: appsettings.json:13-18

Logging:LogLevel:Microsoft.AspNetCore

Log level for ASP.NET Core framework logs.

Type: String
Required: No
Default: Warning
Environment Variable: Logging__LogLevel__Microsoft.AspNetCore

Example:

Logging__LogLevel__Microsoft.AspNetCore="Warning"

See: appsettings.json:16

Logging:LogLevel:Microsoft.EntityFrameworkCore

Log level for Entity Framework Core database logs.

Type: String
Required: No
Default: Not set (inherits from Default)
Environment Variable: Logging__LogLevel__Microsoft.EntityFrameworkCore

Examples:

# Debug SQL queries (development)
Logging__LogLevel__Microsoft.EntityFrameworkCore="Information"

# Minimal logging (production)
Logging__LogLevel__Microsoft.EntityFrameworkCore="Warning"

AllowedHosts

Semicolon-separated list of allowed host headers for host filtering middleware.

Type: String
Required: No
Default: * (all hosts allowed)
Environment Variable: AllowedHosts

Examples:

# Allow all (default)
AllowedHosts="*"

# Specific domains
AllowedHosts="api.happyhabitat.com;api-internal.happyhabitat.com"

See: appsettings.json:19

ASPNETCORE_ENVIRONMENT

Specifies the hosting environment.

Type: String
Required: No
Default: Production
Allowed Values: Development, Staging, Production
Environment Variable: ASPNETCORE_ENVIRONMENT

Examples:

ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_ENVIRONMENT=Staging
ASPNETCORE_ENVIRONMENT=Development

Impact:

Development:
- Swagger UI enabled (Program.cs:203-211)
- Dummy data seeding (Program.cs:270-275)
- Allows default JWT key
- Allows default CORS origins
Production:
- Swagger UI disabled
- HTTPS redirection enabled (Program.cs:220-223)
- Requires explicit JWT key and CORS origins
- Strict validation on startup

ASPNETCORE_URLS

URLs the application listens on.

Type: String (semicolon-separated)
Required: No
Default: http://localhost:5000
Environment Variable: ASPNETCORE_URLS

Examples:

# HTTP only
ASPNETCORE_URLS="http://*:5080"

# HTTPS only
ASPNETCORE_URLS="https://*:5443"

# Both HTTP and HTTPS
ASPNETCORE_URLS="http://*:5080;https://*:5443"

# Specific IP
ASPNETCORE_URLS="http://10.0.0.5:5080"

Frontend Configuration

Frontend configuration is managed through environment files, not environment variables. Configuration is baked into the build at compile time.

Development (environment.ts)

export const environment = {
  production: false,
  apiUrl: 'http://localhost:5080/api',
  apiVersion: 'v1',
  appName: 'Happy Habitat',
  appVersion: '0.0.0',
  logging: {
    level: LogLevel.DEBUG,
    enableConsole: true,
    enableRemote: false,
    enableStackTraces: true
  },
  auth: {
    useMockAuth: false
  }
};

See: environment.ts:3-21

Production (environment.prod.ts)

export const environment = {
  production: true,
  apiUrl: 'https://api.happyhabitat.com/api',
  apiVersion: 'v1',
  appName: 'Happy Habitat',
  appVersion: '1.0.0',
  logging: {
    level: LogLevel.WARN,
    enableConsole: false,
    enableRemote: true,
    enableStackTraces: true
  },
  auth: {
    useMockAuth: false
  }
};

See: environment.prod.ts:3-21

Frontend Configuration Options

production

Whether the application is running in production mode.

Type: Boolean
Default: false (development), true (production)
Impact: Enables production optimizations, disables debug features

apiUrl

Base URL for backend API requests.

Type: String
Required: Yes
Format: https://domain.com/api (no trailing slash)

Examples:

// Development
apiUrl: 'http://localhost:5080/api'

// Production
apiUrl: 'https://api.happyhabitat.com/api'

// Staging
apiUrl: 'https://staging-api.happyhabitat.com/api'

This value is compiled into the JavaScript bundle. To change it, you must rebuild the application.

apiVersion

API version identifier.

Type: String
Default: v1

appName

Application display name.

Type: String
Default: Happy Habitat

appVersion

Application version number.

Type: String
Default: 0.0.0
Recommendation: Update with each release

logging.level

Minimum log level for client-side logging.

Type: LogLevel enum
Values: DEBUG, INFO, WARN, ERROR
Default: DEBUG (development), WARN (production)

logging.enableConsole

Whether to output logs to browser console.

Type: Boolean
Default: true (development), false (production)

logging.enableRemote

Whether to send logs to remote logging service.

Type: Boolean
Default: false (development), true (production)

logging.enableStackTraces

Whether to include stack traces in error logs.

Type: Boolean
Default: true

auth.useMockAuth

Whether to use mock authentication (for testing without backend).

Type: Boolean
Default: false
Recommendation: Always false in production

Configuration Templates

Development Environment

Backend (appsettings.Development.json):

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(local);Database=HappyHabitat;Trusted_Connection=True;TrustServerCertificate=True;"
  },
  "Database": {
    "RecreateOnStartup": false
  },
  "Jwt": {
    "Key": "YourSuperSecretKeyThatShouldBeAtLeast32CharactersLong!",
    "Issuer": "HappyHabitat",
    "Audience": "HappyHabitatUsers"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft.AspNetCore": "Information",
      "Microsoft.EntityFrameworkCore": "Information"
    }
  }
}

Frontend: Uses environment.ts (see above)

Production Environment

Backend (appsettings.Production.json or environment variables):

# Required
ConnectionStrings__DefaultConnection="Server=prod-sql.example.com;Database=HappyHabitat;User Id=appuser;Password=SecureP@ss123!;TrustServerCertificate=False;Encrypt=True;"
Jwt__Key="8f3K9mP2nQ5rS7tV4wX6yZ1aB3cD5eF7gH9jK2lM4nP6qR8sT0uV2wX4yZ6aB8c"
Cors__Origins="https://app.happyhabitat.com"
Database__RecreateOnStartup=false

# Optional
Jwt__Issuer="HappyHabitat"
Jwt__Audience="HappyHabitatUsers"
Logging__LogLevel__Default="Warning"
Logging__LogLevel__Microsoft.AspNetCore="Warning"
AllowedHosts="api.happyhabitat.com"
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS="https://*:443"

Frontend: Build with production configuration:

ng build --configuration production

This uses environment.prod.ts with production settings.

Docker Environment

docker-compose.yml:

version: '3.8'

services:
  api:
    image: happyhabitat-api:latest
    ports:
      - "80:80"
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ConnectionStrings__DefaultConnection=Server=db;Database=HappyHabitat;User Id=sa;Password=SecureP@ss123!;TrustServerCertificate=True;
      - Jwt__Key=8f3K9mP2nQ5rS7tV4wX6yZ1aB3cD5eF7gH9jK2lM4nP6qR8sT0uV2wX4yZ6aB8c
      - Jwt__Issuer=HappyHabitat
      - Jwt__Audience=HappyHabitatUsers
      - Cors__Origins=https://app.happyhabitat.com
      - Database__RecreateOnStartup=false
    depends_on:
      - db
    volumes:
      - ./uploads:/app/uploads

  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=SecureP@ss123!
    ports:
      - "1433:1433"
    volumes:
      - sqldata:/var/opt/mssql

  frontend:
    image: happyhabitat-frontend:latest
    ports:
      - "8080:80"

volumes:
  sqldata:

Azure App Service

Configure application settings via Azure Portal or CLI:

az webapp config appsettings set \
  --name happyhabitat-api \
  --resource-group happyhabitat-rg \
  --settings \
  ASPNETCORE_ENVIRONMENT=Production \
  Jwt__Key="8f3K9mP2nQ5rS7tV4wX6yZ1aB3cD5eF7gH9jK2lM4nP6qR8sT0uV2wX4yZ6aB8c" \
  Jwt__Issuer="HappyHabitat" \
  Jwt__Audience="HappyHabitatUsers" \
  Cors__Origins="https://app.happyhabitat.com" \
  Database__RecreateOnStartup=false

az webapp config connection-string set \
  --name happyhabitat-api \
  --resource-group happyhabitat-rg \
  --connection-string-type SQLAzure \
  --settings DefaultConnection="Server=tcp:happyhabitat.database.windows.net,1433;Database=HappyHabitat;User ID=admin;Password=SecureP@ss123!;Encrypt=True;"

Security Best Practices

Sensitive Data

Never commit sensitive data to source control:

JWT keys
Database passwords
API keys
Connection strings with credentials

Secrets Management

Options:

Environment Variables - Simple, works everywhere
Azure Key Vault - Centralized secret management
AWS Secrets Manager - For AWS deployments
Docker Secrets - For Docker Swarm
Kubernetes Secrets - For Kubernetes deployments

Azure Key Vault Integration

# Install package
dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets

# Configure in Program.cs
builder.Configuration.AddAzureKeyVault(
    new Uri($"https://{keyVaultName}.vault.azure.net/"),
    new DefaultAzureCredential());

Validation Checklist

Before deploying to production, verify:

Jwt:Key is set to a secure, unique value (minimum 32 characters)
Cors:Origins includes all frontend URLs
Database:RecreateOnStartup is false
Connection string uses secure credentials
Connection string enables encryption (Encrypt=True)
ASPNETCORE_ENVIRONMENT is set to Production
Logging level is set to Warning or higher
Secrets are not in source control
Frontend environment.prod.ts has correct API URL

Troubleshooting

Application Fails to Start

Check logs for validation errors:

# Linux systemd
sudo journalctl -u happyhabitat-api -n 100

# Docker
docker logs container-name

# Azure App Service
az webapp log tail --name happyhabitat-api --resource-group happyhabitat-rg

Common issues:

Missing or invalid Jwt:Key
Missing Cors:Origins in production
Database:RecreateOnStartup=true in production
Invalid connection string

CORS Errors

Verify:

Cors:Origins includes frontend URL exactly (no trailing slash)
Protocol matches (http vs https)
Port is included if non-standard

Database Connection Fails

Verify:

Connection string format is correct
Database server is accessible
Credentials are correct
Firewall allows connection
SQL Server is running

Next Steps

Backend Deployment - Deploy the API
Frontend Deployment - Deploy the client
Database Setup - Configure SQL Server

Getting Started

Core Features

User Guides

Deployment

​Overview

​Configuration Hierarchy

​Environment Variable Format

​Backend Configuration

​Required Settings

​ConnectionStrings:DefaultConnection

​Jwt:Key

​Cors:Origins

​Database:RecreateOnStartup

​Optional Settings

​Jwt:Issuer

​Jwt:Audience

​Logging:LogLevel:Default

​Logging:LogLevel:Microsoft.AspNetCore

​Logging:LogLevel:Microsoft.EntityFrameworkCore

​AllowedHosts

​ASPNETCORE_ENVIRONMENT

​ASPNETCORE_URLS

​Frontend Configuration

​Development (environment.ts)

​Production (environment.prod.ts)

​Frontend Configuration Options

​production

​apiUrl

​apiVersion

​appName

​appVersion

​logging.level

​logging.enableConsole

​logging.enableRemote

​logging.enableStackTraces

​auth.useMockAuth

​Configuration Templates

​Development Environment

​Production Environment

​Docker Environment

​Azure App Service

​Security Best Practices

​Sensitive Data

​Secrets Management

​Azure Key Vault Integration

​Validation Checklist

​Troubleshooting

​Application Fails to Start

​CORS Errors

​Database Connection Fails

​Next Steps

Build docs developers (and LLMs) love

Overview

Configuration Hierarchy

Environment Variable Format

Backend Configuration

Required Settings

ConnectionStrings:DefaultConnection

Jwt:Key

Cors:Origins

Database:RecreateOnStartup

Optional Settings

Jwt:Issuer

Jwt:Audience

Logging:LogLevel:Default

Logging:LogLevel:Microsoft.AspNetCore

Logging:LogLevel:Microsoft.EntityFrameworkCore

AllowedHosts

ASPNETCORE_ENVIRONMENT

ASPNETCORE_URLS

Frontend Configuration

Development (environment.ts)

Production (environment.prod.ts)

Frontend Configuration Options

production

apiUrl

apiVersion

appName

appVersion

logging.level

logging.enableConsole

logging.enableRemote

logging.enableStackTraces

auth.useMockAuth

Configuration Templates

Development Environment

Production Environment

Docker Environment

Azure App Service

Security Best Practices

Sensitive Data

Secrets Management

Azure Key Vault Integration

Validation Checklist

Troubleshooting

Application Fails to Start

CORS Errors

Database Connection Fails

Next Steps