Environment Configuration Guide

This guide explains how to configure environment variables for all three environments: Local, Development (Azure), and Production (Azure).

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Environment Architecture                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  LOCAL (Development Machine)                                                 │
│  ┌────────────────┐         ┌────────────────┐         ┌─────────────────┐  │
│  │   Frontend     │ ──────▶ │    Backend     │ ──────▶ │  MongoDB Atlas  │  │
│  │ localhost:3000 │         │ localhost:8080 │         │    (Cloud)      │  │
│  └────────────────┘         └────────────────┘         └─────────────────┘  │
│                                                                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  DEVELOPMENT (Azure - develop branch)                                        │
│  ┌────────────────────────┐      ┌───────────────────────────────────────┐  │
│  │      Frontend          │ ───▶ │           Backend                      │  │
│  │ purple-sky-081177603   │      │ ctrl-audio-backend-dev                 │  │
│  │ .6.azurestaticapps.net │      │ .thankfulsmoke-fb049d11.westeurope     │  │
│  └────────────────────────┘      │ .azurecontainerapps.io                 │  │
│                                  └───────────────────────────────────────┘  │
│                                                                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  PRODUCTION (Azure - main branch)                                            │
│  ┌────────────────────────┐      ┌───────────────────────────────────────┐  │
│  │      Frontend          │ ───▶ │           Backend                      │  │
│  │ lively-pebble-091ba4e03│      │ ctrl-audio-backend                     │  │
│  │ .6.azurestaticapps.net │      │ .thankfulsmoke-fb049d11.westeurope     │  │
│  └────────────────────────┘      │ .azurecontainerapps.io                 │  │
│                                  └───────────────────────────────────────┘  │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Environment URLs Reference

Environment	Frontend URL	Backend URL
Local	`http://localhost:3000`	`http://localhost:8080`
Dev	`https://purple-sky-081177603.6.azurestaticapps.net`	`https://ctrl-audio-backend-dev.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io`
Production	`https://lively-pebble-091ba4e03.6.azurestaticapps.net`	`https://ctrl-audio-backend.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io`

1. Local Development Setup

Frontend (`ctrl-audio-front`)

Create or edit src/.env.local:

bash

# API Connection
NEXT_PUBLIC_API_BASE_URL=http://localhost:8080

# NextAuth
NEXTAUTH_SECRET=your-local-secret-32-chars-minimum
NEXTAUTH_URL=http://localhost:3000

# Optional: Google OAuth (if testing OAuth locally)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Backend (`ctrl-audio-back`)

Create or edit .env:

bash

# Server
NODE_ENV=development
PORT=8080

# MongoDB Atlas
MONGODB_URI=mongodb+srv://username:password@your-cluster.mongodb.net/ctrl-audio-dev?retryWrites=true&w=majority

# JWT
JWT_SECRET=your-jwt-secret

# CORS - Frontend origin
ORIGIN=http://localhost:3000

# Azure Storage
AZURE_STORAGE_ACCOUNT_NAME=sonnancewebappstorage00
AZURE_STORAGE_ACCOUNT_KEY=your-storage-account-key
AZURE_STORAGE_CONTAINER_NAME=uploads
STORAGE_PROVIDER=azure

# CDN (optional — run infrastructure/setup-cdn.sh first)
# CDN_URL=sonnance-images-hvcsepc8dkhrbjfp.z01.azurefd.net

# Optional: Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:8080/user/auth/google/callback

Start Local Development

bash

# Terminal 1: Backend
cd ctrl-audio-back
npm run start:dev

# Terminal 2: Frontend
cd ctrl-audio-front
npm run dev

2. GitHub Repository Secrets & Variables

Setup Variables for Frontend Repo (`FF8Dev/ctrl-audio-front`)

Go to: Settings → Secrets and variables → Actions → Variables

Variable Name	Value (Production)	Value (Development)
`NEXT_PUBLIC_API_BASE_URL`	`https://ctrl-audio-backend.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io`	-
`NEXT_PUBLIC_API_BASE_URL_DEV`	`https://ctrl-audio-backend-dev.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io`	-
`NEXTAUTH_URL`	`https://lively-pebble-091ba4e03.6.azurestaticapps.net`	-
`NEXTAUTH_URL_DEV`	`https://purple-sky-081177603.6.azurestaticapps.net`	-

Go to: Settings → Secrets and variables → Actions → Secrets

Secret Name	Description
`NEXTAUTH_SECRET`	Generate with `openssl rand -base64 32`
`AZURE_STATIC_WEB_APPS_API_TOKEN`	Prod SWA deployment token
`AZURE_STATIC_WEB_APPS_API_TOKEN_DEV`	Dev SWA deployment token

Setup Secrets for Backend Repo (`FF8Dev/ctrl-audio-back`)

Go to: Settings → Secrets and variables → Actions → Secrets

Secret Name	Description
`AZURE_CREDENTIALS`	Service principal JSON for Azure login
`MONGODB_URI`	Production MongoDB Atlas connection string
`MONGODB_URI_DEV`	Development MongoDB Atlas connection string
`JWT_SECRET`	JWT signing secret
`AZURE_STORAGE_CONNECTION_STRING`	Azure Blob Storage connection string
`GOOGLE_CLIENT_ID`	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret

3. Azure Container Apps Environment Variables

Run the configuration script or set manually:

Using the Script

bash

cd infrastructure
./configure-env.sh

Manual Configuration via Azure CLI

bash

# Production Backend
az containerapp update \
  --name ctrl-audio-backend \
  --resource-group Sonnance-WebApp \
  --set-env-vars \
    NODE_ENV=production \
    PORT=8080 \
    ORIGIN=https://lively-pebble-091ba4e03.6.azurestaticapps.net \
    CDN_URL=sonnance-images-hvcsepc8dkhrbjfp.z01.azurefd.net \
    GOOGLE_CALLBACK_URL=https://ctrl-audio-backend.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io/user/auth/google/callback

# Development Backend
az containerapp update \
  --name ctrl-audio-backend-dev \
  --resource-group Sonnance-WebApp \
  --set-env-vars \
    NODE_ENV=development \
    PORT=8080 \
    ORIGIN=https://purple-sky-081177603.6.azurestaticapps.net \
    CDN_URL=sonnance-images-hvcsepc8dkhrbjfp.z01.azurefd.net \
    GOOGLE_CALLBACK_URL=https://ctrl-audio-backend-dev.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io/user/auth/google/callback

Setting Secrets in Container Apps

bash

# Set secrets (they're stored securely in Azure)
az containerapp secret set \
  --name ctrl-audio-backend \
  --resource-group Sonnance-WebApp \
  --secrets \
    mongodb-uri="mongodb+srv://..." \
    jwt-secret="your-secret" \
    azure-storage="DefaultEndpointsProtocol=..."

# Reference secrets in env vars
az containerapp update \
  --name ctrl-audio-backend \
  --resource-group Sonnance-WebApp \
  --set-env-vars \
    MONGODB_URI=secretref:mongodb-uri \
    JWT_SECRET=secretref:jwt-secret \
    AZURE_STORAGE_CONNECTION_STRING=secretref:azure-storage

4. Azure Static Web Apps Configuration

Environment variables for Static Web Apps are set during build time via GitHub Actions (see workflow). If you need runtime configuration, create staticwebapp.config.json:

json

{
  "routes": [
    {
      "route": "/api/*",
      "allowedRoles": ["anonymous"]
    }
  ],
  "navigationFallback": {
    "rewrite": "/index.html"
  }
}

5. Google OAuth Setup

For Google OAuth to work in all environments, configure your Google Cloud Console:

Authorized JavaScript Origins:

http://localhost:3000
https://purple-sky-081177603.6.azurestaticapps.net
https://lively-pebble-091ba4e03.6.azurestaticapps.net

Authorized Redirect URIs:

http://localhost:8080/user/auth/google/callback
https://ctrl-audio-backend-dev.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io/user/auth/google/callback
https://ctrl-audio-backend.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io/user/auth/google/callback

6. Testing Your Configuration

Verify Local Setup

bash

# Check frontend can reach backend
curl http://localhost:8080/health

# Check frontend loads
open http://localhost:3000

Verify Azure Dev

bash

# Check backend health
curl https://ctrl-audio-backend-dev.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io/health

# Check frontend
open https://purple-sky-081177603.6.azurestaticapps.net

Verify Azure Production

bash

# Check backend health  
curl https://ctrl-audio-backend.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io/health

# Check frontend
open https://lively-pebble-091ba4e03.6.azurestaticapps.net

7. Quick Troubleshooting

Issue	Solution
CORS errors	Check `ORIGIN` env var in backend matches frontend URL
401 Unauthorized	Check JWT_SECRET is same between frontend/backend
Google OAuth fails	Verify callback URLs in Google Console match environment
Frontend can't reach backend	Check `NEXT_PUBLIC_API_BASE_URL` is correct
Container App not updating	Redeploy with `az containerapp update --image <new-image>`

Summary Checklist

[ ] Local .env files created for both frontend and backend
[ ] GitHub Secrets configured for both repos
[ ] GitHub Variables configured for frontend repo
[ ] Azure Container Apps secrets configured
[ ] Azure Container Apps env vars configured
[ ] Google OAuth redirect URIs updated
[ ] All three environments tested

Environment Configuration Guide ​

Architecture Overview ​

Environment URLs Reference ​

1. Local Development Setup ​

Frontend (ctrl-audio-front) ​

Backend (ctrl-audio-back) ​

Start Local Development ​

2. GitHub Repository Secrets & Variables ​

Setup Variables for Frontend Repo (FF8Dev/ctrl-audio-front) ​

Setup Secrets for Backend Repo (FF8Dev/ctrl-audio-back) ​

3. Azure Container Apps Environment Variables ​

Using the Script ​

Manual Configuration via Azure CLI ​

Setting Secrets in Container Apps ​

4. Azure Static Web Apps Configuration ​

5. Google OAuth Setup ​

Authorized JavaScript Origins: ​

Authorized Redirect URIs: ​

6. Testing Your Configuration ​

Verify Local Setup ​

Verify Azure Dev ​

Verify Azure Production ​

7. Quick Troubleshooting ​

Summary Checklist ​

Environment Configuration Guide

Architecture Overview

Environment URLs Reference

1. Local Development Setup

Frontend (`ctrl-audio-front`)

Backend (`ctrl-audio-back`)

Start Local Development

2. GitHub Repository Secrets & Variables

Setup Variables for Frontend Repo (`FF8Dev/ctrl-audio-front`)

Setup Secrets for Backend Repo (`FF8Dev/ctrl-audio-back`)

3. Azure Container Apps Environment Variables

Using the Script

Manual Configuration via Azure CLI

Setting Secrets in Container Apps

4. Azure Static Web Apps Configuration

5. Google OAuth Setup

Authorized JavaScript Origins:

Authorized Redirect URIs:

6. Testing Your Configuration

Verify Local Setup

Verify Azure Dev

Verify Azure Production

7. Quick Troubleshooting

Summary Checklist