local_development_setup - mamoorkhan/glasslewis GitHub Wiki

Local Development Environment Setup

Complete guide for setting up your local development environment for the GlassLewis Platform.

🛠️ Step 1: Install Development Tools

1.1 Install .NET 8 SDK

Windows:

# Using winget (recommended)
winget install Microsoft.DotNet.SDK.8

# Or download from: https://dotnet.microsoft.com/download/dotnet/8.0

macOS:

# Using Homebrew
brew install --cask dotnet-sdk

# Or using .NET installer
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --version 8.0.100

Linux (Ubuntu/Debian):

# Add Microsoft repository
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

# Install .NET SDK
sudo apt-get update
sudo apt-get install -y dotnet-sdk-8.0

Verify Installation:

dotnet --version
# Should output: 8.0.100 or higher

1.2 Install Node.js and npm

All Platforms:

# Install Node Version Manager (nvm)
# Windows: Use nvm-windows from https://github.com/coreybutler/nvm-windows
# macOS/Linux:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then:
nvm install 20.10.0
nvm use 20.10.0
nvm alias default 20.10.0

Verify Installation:

node --version  # Should output: v20.10.0 or higher
npm --version   # Should output: 10.2.0 or higher

1.3 Install Angular CLI

npm install -g @angular/cli@17
ng version  # Should output Angular CLI 17.x

1.4 Install Azure CLI

Windows:

# Using winget
winget install -e --id Microsoft.AzureCLI

# Or using MSI installer from: https://aka.ms/installazurecliwindows

macOS:

brew install azure-cli

Linux:

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Verify Installation:

az --version
az login  # Test authentication

1.5 Install Git

Windows:

winget install Git.Git

macOS:

# Git comes with Xcode Command Line Tools
xcode-select --install

# Or via Homebrew
brew install git

Linux:

sudo apt-get update
sudo apt-get install git

Configure Git:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

🎯 Step 2: IDE and Editor Setup

2.1 Visual Studio Code (Recommended)

Download and Install:

Download from code.visualstudio.com

Recommended Extensions:

# Install via command line
code --install-extension ms-dotnettools.csharp
code --install-extension Angular.ng-template
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension ms-azure-devops.azure-pipelines
code --install-extension ms-azuretools.vscode-azureresourcegroups
code --install-extension bradlc.vscode-tailwindcss
code --install-extension esbenp.prettier-vscode
code --install-extension ms-playwright.playwright

VS Code Settings (Optional):

// .vscode/settings.json
{
  "dotnet.defaultSolution": "GlassLewis.sln",
  "typescript.preferences.quoteStyle": "single",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },
  "files.exclude": {
    "**/bin": true,
    "**/obj": true,
    "**/node_modules": true
  }
}

2.2 Alternative IDEs

Visual Studio 2022 (Windows/Mac):

Download Visual Studio Community (free)
Ensure ASP.NET and web development workload is installed

JetBrains Rider (Paid):

Full-featured IDE with excellent .NET and Angular support
Includes built-in debugging and testing tools

📁 Step 3: Clone and Setup Project

3.1 Clone Repository

# Clone the repository
git clone https://github.com/your-org/glasslewis-platform.git
cd glasslewis-platform

# Create a new branch for your work
git checkout -b feature/setup-local-development

3.2 Verify Project Structure

# Your directory should look like this:
tree -L 2

📦 glasslewis-platform/
├── 📂 src/
│   ├── 📂 GlassLewis.Api/
│   ├── 📂 GlassLewis.Application/
│   ├── 📂 GlassLewis.Domain/
│   ├── 📂 GlassLewis.Infrastructure/
│   └── 📂 clients/
│       └── 📂 glasslewis.client.angular/
├── 📂 tests/
├── 📂 infra/
├── 📂 .github/
├── 📜 GlassLewis.sln
└── 📜 README.md

🗄️ Step 4: Database Setup

4.1 Install SQL Server LocalDB (Windows)

LocalDB is included with Visual Studio, or install separately:

# Download SQL Server Express LocalDB
# https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/sql-server-express-localdb

Verify LocalDB:

SqlLocalDB info
SqlLocalDB start MSSQLLocalDB

4.2 Alternative: Docker SQL Server (Cross-Platform)

Install Docker:

Windows: Docker Desktop
macOS: Docker Desktop
Linux: Docker Engine

Run SQL Server Container:

# Pull and run SQL Server in Docker
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=GlassLewis123!" \
   -p 1433:1433 --name glasslewis-sql --hostname glasslewis-sql \
   -d mcr.microsoft.com/mssql/server:2022-latest

# Verify container is running
docker ps

Connection String for Docker:

Server=localhost,1433;Database=GlassLewisDb;User Id=sa;Password=GlassLewis123!;Encrypt=false;TrustServerCertificate=true;

4.3 Alternative: SQLite (Simplest Option)

No installation required - uses file-based database:

Data Source=GlassLewisDb.sqlite

🔑 Step 5: Configure Azure Authentication

5.1 Obtain Azure Configuration Values

You need these values from Azure (see Azure Setup Guide):

API_CLIENT_ID=your-api-app-registration-id
CLIENT_APP_ID=your-client-app-registration-id  
TENANT_ID=your-azure-tenant-id
AUTHORITY=https://your-tenant-name.ciamlogin.com/

5.2 Configure API User Secrets

# Navigate to API project
cd src/GlassLewis.Api

# Set user secrets (replace with your actual values)
dotnet user-secrets set "ConnectionStrings:DefaultConnection" "Server=(localdb)\\MSSQLLocalDB;Database=GlassLewisDb;Trusted_Connection=true;MultipleActiveResultSets=true"

dotnet user-secrets set "AzureAd:ClientId" "your-api-client-id"
dotnet user-secrets set "AzureAd:Authority" "https://your-tenant-name.ciamlogin.com/"
dotnet user-secrets set "AzureAd:TenantId" "your-tenant-id"

# Optional: For development logging
dotnet user-secrets set "Logging:LogLevel:Microsoft.AspNetCore.Authentication" "Debug"
dotnet user-secrets set "Logging:LogLevel:Microsoft.AspNetCore.Authorization" "Debug"

# Verify secrets were set
dotnet user-secrets list

5.3 Configure Angular Environment

Edit clients/glasslewis.client.angular/src/environments/environment.development.ts:

export const environment = {
  production: false,
  apiUrl: 'https://localhost:5001',
  msalConfig: {
    auth: {
      clientId: 'your-client-app-id',           // Client app registration ID
      authority: 'https://your-tenant-name.ciamlogin.com/',
      redirectUri: 'http://localhost:4200',
      postLogoutRedirectUri: 'http://localhost:4200'
    },
    cache: {
      cacheLocation: 'sessionStorage',
      storeAuthStateInCookie: false
    },
    system: {
      loggerOptions: {
        loggerCallback: (level: any, message: string) => {
          console.log(`MSAL [${level}]: ${message}`);
        },
        logLevel: 3, // Verbose logging for development
        piiLoggingEnabled: false
      }
    }
  },
  apiConfig: {
    scopes: [`api://your-api-client-id/Company.Read`], // API app registration ID in scope
    uri: 'https://localhost:5001/api/v1/'
  }
};

🚀 Step 6: Build and Run the Application

6.1 Restore Dependencies

Backend (.NET):

# From project root
dotnet restore
dotnet build

# Run tests to verify setup
dotnet test --filter "Category=UnitTests"

Frontend (Angular):

# Navigate to Angular project
cd clients/glasslewis.client.angular

# Install dependencies
npm install

# Verify Angular build
ng build

6.2 Database Migration

# Navigate to API project
cd src/GlassLewis.Api

# Install EF Core tools (if not already installed)
dotnet tool install --global dotnet-ef

# Create and apply migrations
dotnet ef migrations add InitialCreate
dotnet ef database update

# Verify database creation
dotnet ef migrations list

6.3 Run the Application

Terminal 1 - Backend API:

cd src/GlassLewis.Api
dotnet run

# You should see:
# info: Microsoft.Hosting.Lifetime[14]
#       Now listening on: https://localhost:5001
#       Now listening on: http://localhost:5000

Terminal 2 - Frontend Angular:

cd clients/glasslewis.client.angular
ng serve

# You should see:
# ** Angular Live Development Server is listening on localhost:4200 **

Terminal 3 - Database (if using Docker):

# Keep SQL Server container running
docker logs glasslewis-sql

✅ Step 7: Verify Your Setup

7.1 Test Backend API

Open browser to:

Swagger UI: https://localhost:5001/swagger
Health Check: https://localhost:5001/health

Test API endpoint:

# This should return 401 Unauthorized (expected without auth)
curl -k https://localhost:5001/api/v1/companies

7.2 Test Frontend Application

Open browser to:

Angular App: http://localhost:4200

Expected behavior:

Page loads showing login button
Click "Sign In" redirects to Azure
After login, redirected back to app
Should be able to make authenticated API calls

7.3 Test Authentication Flow

Check browser network tab:

Authorization request to your-tenant-name.ciamlogin.com
Token request after successful login
API calls with Authorization: Bearer header

Check browser console:

// Should see MSAL logging messages
MSAL [Info]: Successful login
MSAL [Info]: Token acquired silently

🛠️ Step 8: Development Tools Setup

8.1 Install Development Certificates

Trust HTTPS certificates:

# .NET development certificate
dotnet dev-certs https --trust

# Verify certificate
dotnet dev-certs https --check

8.2 Configure Hot Reload

API Hot Reload:

# Enable hot reload for .NET
cd src/GlassLewis.Api
dotnet watch run

Angular Hot Reload:

# Already enabled by default with ng serve
cd clients/glasslewis.client.angular
ng serve --open  # Opens browser automatically

8.3 Setup Testing Environment

Install Playwright for E2E tests:

cd tests/ui/GlassLewis.Client.Angular.UiTests.Playwright
dotnet build
pwsh bin/Debug/net8.0/playwright.ps1 install

# Run a test to verify setup
dotnet test

8.4 Configure Debugging

VS Code Debug Configuration (.vscode/launch.json):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch (API)",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${workspaceFolder}/src/GlassLewis.Api/bin/Debug/net8.0/GlassLewis.Api.dll",
      "args": [],
      "cwd": "${workspaceFolder}/src/GlassLewis.Api",
      "console": "internalConsole",
      "stopAtEntry": false,
      "env": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    {
      "name": "Launch Chrome (Angular)",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:4200",
      "webRoot": "${workspaceFolder}/clients/glasslewis.client.angular/src"
    }
  ],
  "compounds": [
    {
      "name": "Launch Full Stack",
      "configurations": [".NET Core Launch (API)", "Launch Chrome (Angular)"]
    }
  ]
}

🐛 Common Setup Issues & Solutions

Issue: "dotnet command not found"

Solution:

# Check PATH variable includes .NET
echo $PATH | grep dotnet

# Reload shell configuration
source ~/.bashrc  # Linux
source ~/.zshrc   # macOS with zsh

Issue: "LocalDB instance not found"

Solution:

# Windows: Start LocalDB
SqlLocalDB start MSSQLLocalDB

# Or use Docker SQL Server instead
docker start glasslewis-sql

Issue: "ng command not found"

Solution:

# Reinstall Angular CLI globally
npm uninstall -g @angular/cli
npm install -g @angular/cli@17

# Clear npm cache
npm cache clean --force

Issue: SSL Certificate Errors

Solution:

# Trust .NET development certificates
dotnet dev-certs https --clean
dotnet dev-certs https --trust

# For Chrome: Enable localhost certificates
# chrome://flags/#allow-insecure-localhost

Issue: Port Already in Use

Solution:

# Find process using port
netstat -ano | findstr :5001  # Windows
lsof -i :5001                 # macOS/Linux

# Kill process or use different port
dotnet run --urls="https://localhost:5002;http://localhost:5003"
ng serve --port 4201

Issue: Authentication Redirect Loops

Solution:

Check redirect URIs in Azure app registration
Verify environment.ts configuration
Clear browser cache and cookies
Check for HTTPS/HTTP mismatches

📋 Daily Development Workflow

Starting Development Session

# 1. Pull latest changes
git pull origin main

# 2. Restore dependencies (if package files changed)
dotnet restore
cd clients/glasslewis.client.angular && npm install

# 3. Start database (if using Docker)
docker start glasslewis-sql

# 4. Start API with hot reload
cd src/GlassLewis.Api && dotnet watch run

# 5. Start Angular (new terminal)
cd clients/glasslewis.client.angular && ng serve

Running Tests

# Unit tests
dotnet test --filter "Category=UnitTests"

# Integration tests  
dotnet test --filter "Category=IntegrationTests"

# E2E tests
cd tests/ui/GlassLewis.Client.Angular.UiTests.Playwright
dotnet test

# Angular tests
cd clients/glasslewis.client.angular
ng test
ng e2e

Code Quality Checks

# Format code
dotnet format
cd clients/glasslewis.client.angular && npm run lint

# Build for production
dotnet build -c Release
cd clients/glasslewis.client.angular && ng build --configuration production

🎯 Next Steps

After completing local setup:

Test Authentication Flow - Verify login works

📞 Need Help?

Setup Issues: Common Issues FAQ
Authentication Problems: Authentication Troubleshooting