CI/CD Setup Guide for Ctrl-Audio

This guide explains how to set up the automated CI/CD pipeline for Ctrl-Audio using GitHub Actions and Azure free-tier resources.

📋 Architecture Overview

┌─────────────────┐     ┌──────────────────────┐
│  GitHub Repo    │────▶│  GitHub Actions      │
│  (monorepo)     │     │  (CI/CD Pipeline)    │
└─────────────────┘     └──────────┬───────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
         ┌──────────────────┐          ┌──────────────────┐
         │ Azure Static     │          │ Azure Container  │
         │ Web Apps         │          │ Apps             │
         │ (Next.js)        │◀────────▶│ (NestJS)         │
         └──────────────────┘          └────────┬─────────┘
                                                │
                        ┌───────────────────────┼───────────────────────┐
                        ▼                       ▼                       ▼
              ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
              │ MongoDB Atlas   │    │ Azure Blob      │    │ Azure Container │
              │ (Existing)      │    │ Storage         │    │ Registry        │
              └─────────────────┘    │ (Existing)      │    │ (New)           │
                                     └─────────────────┘    └─────────────────┘

==============================================

SETUP COMPLETE - Resource Summary

==============================================

Azure Resources Created: ├── Resource Group: Sonnance-WebApp ├── Container Registry: sonnanceacr (sonnanceacr.azurecr.io) ├── Container Apps Environment: sonnance-env ├── Backend Container App (Prod): ctrl-audio-backend ├── Backend Container App (Dev): ctrl-audio-backend-dev ├── Static Web App (Prod): ctrl-audio-frontend └── Static Web App (Dev): ctrl-audio-frontend-dev

Application URLs: ├── Backend (Prod): https://ctrl-audio-backend.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io ├── Backend (Dev): https://ctrl-audio-backend-dev.thankfulsmoke-fb049d11.westeurope.azurecontainerapps.io ├── Frontend (Prod): https://lively-pebble-091ba4e03.6.azurestaticapps.net └── Frontend (Dev): https://purple-sky-081177603.6.azurestaticapps.net

💰 Free Tier Limits

Service	Free Tier
GitHub Actions	2,000 min/month (private repos)
Azure Static Web Apps	100GB bandwidth, 2 custom domains
Azure Container Apps	180K vCPU-sec/month, 360K GiB-sec/month
Azure Container Registry (Basic)	10GB storage

🚀 Setup Steps

Step 1: Prerequisites

Azure CLI installed: Install Guide
Docker installed (for local testing)
GitHub repository with monorepo structure

bash

# Login to Azure
az login --tenant d696653f-8bd7-4877-a422-7bb00fe509c1

# Verify subscription
az account show

Step 3: Run the Infrastructure Setup Script

bash

# Navigate to the infrastructure folder
cd infrastructure

# Make the script executable
chmod +x setup-azure.sh

# Run the setup script
./setup-azure.sh

The script will:

✅ Set the correct Azure subscription
✅ Create Azure Container Registry (for Docker images)
✅ Create Container Apps Environment
✅ Create Backend Container Apps (dev & prod)
✅ Create Static Web Apps for Frontend (dev & prod)
✅ Create Service Principal for GitHub Actions
✅ Output all secrets needed for GitHub

Step 4: Configure GitHub Secrets

After running the script, add these secrets to your GitHub repository:

Go to: Settings → Secrets and variables → Actions → New repository secret

Secret Name	Description
`ACR_USERNAME`	Azure Container Registry username
`ACR_PASSWORD`	Azure Container Registry password
`AZURE_CREDENTIALS`	Service Principal JSON (for Container Apps)
`AZURE_STATIC_WEB_APPS_API_TOKEN`	SWA deployment token (production)
`AZURE_STATIC_WEB_APPS_API_TOKEN_DEV`	SWA deployment token (development)
`NEXTAUTH_SECRET`	Your NextAuth secret key

Step 5: Configure GitHub Variables

Add these variables (not secrets):

Go to: Settings → Secrets and variables → Actions → Variables → New repository variable

Variable Name	Example Value
`NEXT_PUBLIC_API_URL`	`https://ctrl-audio-backend.xxx.azurecontainerapps.io`
`NEXT_PUBLIC_API_URL_DEV`	`https://ctrl-audio-backend-dev.xxx.azurecontainerapps.io`
`NEXTAUTH_URL`	`https://ctrl-audio-frontend.xxx.azurestaticapps.net`
`NEXTAUTH_URL_DEV`	`https://ctrl-audio-frontend-dev.xxx.azurestaticapps.net`

Step 6: Configure Backend Environment Variables

Set environment variables in Azure Container Apps:

bash

# Production
az containerapp update \
  --name ctrl-audio-backend \
  --resource-group Sonnance-WebApp \
  --set-env-vars \
    "NODE_ENV=production" \
    "PORT=8080" \
    "MONGODB_URI=secretref:mongodb-uri" \
    "JWT_SECRET=secretref:jwt-secret" \
    "AZURE_STORAGE_CONNECTION_STRING=secretref:azure-storage"

# Development (similar, with dev values)
az containerapp update \
  --name ctrl-audio-backend-dev \
  --resource-group Sonnance-WebApp \
  --set-env-vars \
    "NODE_ENV=development" \
    "PORT=8080" \
    "MONGODB_URI=secretref:mongodb-uri-dev"

📁 Repository Structure

After setup, your monorepo should look like this:

ctrl-audio/
├── .github/
│   └── workflows/
│       ├── backend-deploy.yml    # Backend CI/CD
│       └── frontend-deploy.yml   # Frontend CI/CD
├── infrastructure/
│   ├── setup-azure.sh            # Azure setup script
│   └── cleanup-azure.sh          # Cleanup script
├── ctrl-audio-back/
│   ├── Dockerfile                # Backend Docker config
│   ├── .dockerignore
│   └── ... (NestJS app)
└── ctrl-audio-front/
    ├── Dockerfile                # Frontend Docker config
    ├── .dockerignore
    └── ... (Next.js app)

🔄 Deployment Flow

Development Branch (`develop`)

Push to develop branch
GitHub Actions triggers
Runs tests and lint
Builds Docker image
Pushes to ACR with develop tag
Deploys to *-dev resources

Production Branch (`main`)

Push/merge to main branch
GitHub Actions triggers
Runs tests and lint
Builds Docker image
Pushes to ACR with latest tag
Deploys to production resources

🧪 Testing Locally

Test Backend Docker Build

bash

cd ctrl-audio-back

# Build
docker build -t ctrl-audio-backend:local .

# Run
docker run -p 8080:8080 \
  -e NODE_ENV=development \
  -e MONGODB_URI="your-mongodb-uri" \
  ctrl-audio-backend:local

Test Frontend Docker Build

bash

cd ctrl-audio-front

# Build (with build args)
docker build \
  --build-arg NEXT_PUBLIC_API_URL=http://localhost:8080 \
  --build-arg NEXTAUTH_URL=http://localhost:3000 \
  --build-arg NEXTAUTH_SECRET=your-secret \
  -t ctrl-audio-frontend:local .

# Run
docker run -p 3000:3000 ctrl-audio-frontend:local

🔧 Troubleshooting

Common Issues

ACR Push Fails: Verify ACR_USERNAME and ACR_PASSWORD secrets are correct

Container App Not Starting: Check logs with:

bash

az containerapp logs show --name ctrl-audio-backend --resource-group Sonnance-WebApp

SWA Deployment Fails: Verify the API token and check build output

Useful Commands

bash

# View Container App logs
az containerapp logs show \
  --name ctrl-audio-backend \
  --resource-group Sonnance-WebApp \
  --follow

# Restart Container App
az containerapp revision restart \
  --name ctrl-audio-backend \
  --resource-group Sonnance-WebApp

# Check SWA deployment status
az staticwebapp show \
  --name ctrl-audio-frontend \
  --resource-group Sonnance-WebApp

# List all resources in resource group
az resource list --resource-group Sonnance-WebApp --output table

🗑️ Cleanup

To remove all created Azure resources:

bash

cd infrastructure
chmod +x cleanup-azure.sh
./cleanup-azure.sh

Note: This will NOT delete the resource group itself, only the resources created by the setup script.

📊 Cost Estimation

With typical development usage:

Resource	Estimated Monthly Cost
Container Registry (Basic)	~$5/month
Container Apps (within free tier)	$0
Static Web Apps (Free tier)	$0
Total	~$5/month

Costs may increase with higher usage beyond free tier limits.

CI/CD Setup Guide for Ctrl-Audio ​

📋 Architecture Overview ​

SETUP COMPLETE - Resource Summary ​

💰 Free Tier Limits ​

🚀 Setup Steps ​

Step 1: Prerequisites ​

Step 2: Login to Azure ​

Step 3: Run the Infrastructure Setup Script ​

Step 4: Configure GitHub Secrets ​

Step 5: Configure GitHub Variables ​

Step 6: Configure Backend Environment Variables ​

📁 Repository Structure ​

🔄 Deployment Flow ​

Development Branch (develop) ​

Production Branch (main) ​

🧪 Testing Locally ​

Test Backend Docker Build ​

Test Frontend Docker Build ​

🔧 Troubleshooting ​

Common Issues ​

Useful Commands ​

🗑️ Cleanup ​

📊 Cost Estimation ​

🔗 Useful Links ​

CI/CD Setup Guide for Ctrl-Audio

📋 Architecture Overview

SETUP COMPLETE - Resource Summary

💰 Free Tier Limits

🚀 Setup Steps

Step 1: Prerequisites

Step 2: Login to Azure

Step 3: Run the Infrastructure Setup Script

Step 4: Configure GitHub Secrets

Step 5: Configure GitHub Variables

Step 6: Configure Backend Environment Variables

📁 Repository Structure

🔄 Deployment Flow

Development Branch (`develop`)

Production Branch (`main`)

🧪 Testing Locally

Test Backend Docker Build

Test Frontend Docker Build

🔧 Troubleshooting

Common Issues

Useful Commands

🗑️ Cleanup

📊 Cost Estimation

🔗 Useful Links