Developer Setup

Prerequisites

Install these tools before starting. Skip any that are already installed.

Docker Desktop

Required for LocalStack and Lambda testing. Enable WSL2 integration.

.NET 6.0 SDK

Required to build and run Dash360 and Lambda functions.

Terraform

Deploys Lambda infrastructure to LocalStack. Install to C:\terraform\.

LocalStack Pro

Required for Lambda function support. Contact Jeff for the Pro token.

Also install:

AWS CLI (required by Terraform for Step Functions in LocalStack) — install guide
Visual Studio or VS Code — for development
SQL Server Developer Edition — local database

Step 1: SQL Server Configuration

Lambda functions run inside Docker containers and need TCP/IP access to your local SQL Server. By default, SQL Server Developer Edition only supports Windows Authentication — you must enable Mixed Mode.

Enable Mixed Mode Authentication

Open SQL Server Management Studio (SSMS)
Connect to your local SQL Server instance
Right-click the server → Properties → Security tab
Under “Server authentication”, select SQL Server and Windows Authentication mode
Click OK
Restart the SQL Server service (required for the change to take effect)

Enable TCP/IP

Open SQL Server Configuration Manager
- Start Menu → “SQL Server Configuration Manager”, or run: SQLServerManager16.msc
Navigate to: SQL Server Network Configuration → Protocols for MSSQLSERVER
Right-click TCP/IP → Enable
Right-click TCP/IP → Properties → IP Addresses tab
Scroll to the IPAll section, set TCP Port to 1433
Restart SQL Server service

Create Database User for Lambda Access

-- Create login for Lambda/Docker access
CREATE LOGIN [wsl] WITH PASSWORD = 'wslpassword',
    CHECK_EXPIRATION = OFF,
    CHECK_POLICY = OFF;

-- Grant sysadmin role (development only — use specific permissions in production)
ALTER SERVER ROLE [sysadmin] ADD MEMBER [wsl];

-- Create database user
USE [Dash360];
CREATE USER [wsl] FOR LOGIN [wsl];
ALTER ROLE [db_owner] ADD MEMBER [wsl];

Allow Firewall Access

# Run PowerShell as Administrator
New-NetFirewallRule -DisplayName "SQL Server" -Direction Inbound -Protocol TCP -LocalPort 1433 -Action Allow

Find Your IP Address

Docker containers cannot use localhost to reach your SQL Server. Use your machine’s actual IP:

ipconfig | findstr "IPv4"

Look for the IPv4 Address on your main network adapter (not Docker or WSL adapters).

Step 2: LocalStack Pro Setup

Get your auth token

Install the LocalStack CLI

Download the Windows LocalStack CLI from the LocalStack website (Getting Started section). Extract localstack.exe to C:\localstack\.Add to your PATH:

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path","User") + ";C:\localstack",
  "User"
)

Set your auth token

localstack auth set-token <YOUR_AUTH_TOKEN>

Step 3: Create the `.env` File

The .env file in the solution root is git-ignored. It configures LocalStack, Terraform, and the web app with your local IP and database credentials.

# Copy the template
cp .env.template .env

Edit .env and set these values:

# Get from Jeff or the LocalStack dashboard
LOCALSTACK_AUTH_TOKEN=your-actual-token-here

# Your machine's IPv4 address from ipconfig
DEVELOPER_IP_ADDRESS=192.168.x.x

# SQL Server connection string — update IP to match yours
DEVELOPER_SQL_CONNECTION=Server=192.168.x.x,1433;User Id=wsl;Password=wslpassword;Database=Dash360;

# Webhook endpoint — host.docker.internal usually works with Docker Desktop
WEBHOOK_ENDPOINT=http://host.docker.internal:53720/Admin/LambdaExport/ProgressWebhook

Both Terraform and the C# app read from this single .env file. Keep it updated when your IP changes.

Step 4: Start LocalStack

cd Dash360.LocalStack
docker compose up -d

Wait for LocalStack to report healthy (~30 seconds):

docker compose ps
# Look for "healthy" status

curl http://localhost:4566/health
# Should show lambda, s3, sqs, dynamodb, etc. as "available"

LocalStack Web UI: After starting, browse to http://localhost:8080 to inspect S3 buckets, SQS queues, Lambda functions, and logs.

Step 5: Build and Deploy to LocalStack

Run this PowerShell script from Windows PowerShell (not WSL):

cd Dash360.Infrastructure\terraform\environments\localstack
.\deploy-localstack.ps1

The script does everything automatically:

Builds Dash360.Lambda.SharedLayer (Release)
Builds Dash360.Lambda (Release)
Publishes Lambda for Linux runtime (linux-x64)
Runs terraform init (uses committed lock file for consistent provider versions)
Runs terraform apply -auto-approve

What gets deployed:

SQS Queues (export, import, backup, DLQ)
DynamoDB Tables (jobs, transactions, configuration)
S3 Buckets with tenant folder structure
Lambda Functions (ExportRouter, WebhookRouter, RiskCategories, RiskTypes, PremiumPay, and more)
EventBridge rules for progress notifications
SSM Parameters for tenant configuration

If Terraform hangs (known issue with AWS provider v5.100.0 + LocalStack):

Press Ctrl+C
Delete state: del terraform.tfstate*
Restart LocalStack: docker compose restart (from Dash360.LocalStack)
Re-run the script

Step 6: Configure `appsettings.Development.json`

This file is checked in with LocalStack defaults. Verify these settings match your setup:

{
  "AWS": {
    "ServiceURL": "http://localhost:4566",
    "UseLocalStack": true,
    "SQS": {
      "ExportQueueUrl": "http://sqs.us-west-2.localhost.localstack.cloud:4566/000000000000/dash360-export-queue-localstack"
    },
    "DynamoDB": {
      "JobsTableName": "dash360-processing-jobs-localstack"
    },
    "StepFunctions": {
      "BackupProjectArn": ""
    }
  },
  "FeatureFlags": {
    "NewBackupProject": true
  }
}

BackupProjectArn is empty because LocalStack uses a workaround via AWS CLI during terraform apply. To get the ARN after deployment:

aws --endpoint-url=http://localhost:4566 stepfunctions list-state-machines --region us-west-2

Copy the ARN into appsettings.Development.json if you need to test Backup Project locally.

Step 7: Run the Web App

Open the solution in Visual Studio and run the Dash360 project in debug mode (F5).

Step 8: Verify Everything Works

Test an Export

Navigate to Admin → Import/Export → Export
Select a data type (e.g., “Risk Categories”)
Click Export

You should see:

A notification in the bell icon with a progress bar
The export appear in the “Recent Exports” grid
Auto-download when complete

Test Backup Project

Navigate to Admin → Projects
Select any project
Click Backup Project (New)

You should see a single notification with step-based progress: 25% → 50% → 75% → 100%, then a download button.

Run Lambda Tests

# Run all Lambda tests (600+ tests)
dotnet test Dash360.Lambda.Tests/Dash360.Lambda.Tests.csproj

# Run specific tests
dotnet test Dash360.Lambda.Tests/Dash360.Lambda.Tests.csproj --filter "ExportFunctionTests"

Quick Start Checklist

SQL Server: Mixed Mode enabled, TCP/IP enabled, wsl user created, port 1433 firewall rule added
Docker Desktop: Running, WSL2 integration enabled
LocalStack Pro: Token obtained, CLI installed, auth token configured
.env file: Created from template, IP addresses updated
LocalStack: Started (docker compose up -d), reports healthy
Lambda deployed: .\deploy-localstack.ps1 ran successfully
appsettings.Development.json: Settings verified
Web app: Running in Visual Studio
Exports: Test export completes with notification and auto-download

Re-Deploying After Code Changes

Any time you modify Lambda function code:

cd Dash360.Infrastructure\terraform\environments\localstack
.\deploy-localstack.ps1

Key File Locations

Component	Path
Docker Compose	`Dash360.LocalStack/docker-compose.yml`
Terraform (LocalStack)	`Dash360.Infrastructure/terraform/environments/localstack/main.tf`
Deploy Script	`Dash360.Infrastructure/terraform/environments/localstack/deploy-localstack.ps1`
Lambda Functions	`Dash360.Lambda/Functions/`
Lambda Shared Layer	`Dash360.Lambda.SharedLayer/`
Lambda Tests	`Dash360.Lambda.Tests/`
Export Controller	`Dash360/Areas/Admin/Controllers/LambdaExportController.cs`
Export Service	`Dash360/Services/LambdaExportService.cs`
App Settings (local)	`Dash360/appsettings.Development.json`
Env Template	`.env.template`

Troubleshooting

Webhook Notifications Not Working

If exports complete but you don’t see live progress in the notification bell, the webhook endpoint is unreachable from inside LocalStack’s Docker container. The notification flow is:

Lambda → EventBridge → WebhookRouter Lambda → HTTP POST to web app → SignalR → Browser

Verify your port number

Check what port Visual Studio is running the web app on (look at the browser URL). Update .env to match:

WEBHOOK_ENDPOINT=http://host.docker.internal:53720/Admin/LambdaExport/ProgressWebhook

Test connectivity from inside the container

docker exec dash360-localstack curl -s -o /dev/null -w "%{http_code}" \
  http://host.docker.internal:53720/Admin/LambdaExport/ProgressWebhook

200 or 400 = reachable (the endpoint exists)
000 or timeout = not reachable (the problem)

If host.docker.internal doesn't work, use your IP

WEBHOOK_ENDPOINT=http://192.168.x.x:53720/Admin/LambdaExport/ProgressWebhook

Add a Windows Firewall inbound rule

Open Windows Defender Firewall → Advanced Settings → Inbound Rules → New Rule:

Port → TCP → Specific port: 53720
Allow the connection
Name: “Dash360 LocalStack Webhook”

Re-deploy after changing .env

The webhook URL is stored in SSM Parameter Store during terraform apply. Changing .env alone has no effect — re-run the deploy script:

.\deploy-localstack.ps1

Other Common Issues

Issue	Solution
`docker compose up` fails	Ensure Docker Desktop is running with WSL2 integration enabled
LocalStack not healthy	Check `docker logs dash360-localstack`. Verify `.env` has a valid `LOCALSTACK_AUTH_TOKEN`
Terraform hangs on apply	Delete `terraform.tfstate*`, restart LocalStack, re-apply
Exports go to wrong tenant	Check that `ITenantResolutionService` resolves your hostname correctly (`localhost` → `testcustomer`)
“Export service not available”	Ensure `LambdaExportService` is registered in `Startup.cs`. Check `AWS:SQS:ExportQueueUrl` is set
Download button not appearing	Check DynamoDB record for the job — needs `S3Location` in `ResultData`
Backup Project button missing	Set `FeatureFlags:NewBackupProject` to `true` in `appsettings.Development.json`
Terraform state is corrupt	Delete `terraform.tfstate` and `terraform.tfstate.backup`, then re-apply

Architecture & Setup

Standards & Reference

Developer Setup

Prerequisites

Docker Desktop

.NET 6.0 SDK

Terraform

LocalStack Pro

Step 1: SQL Server Configuration

Enable Mixed Mode Authentication

Enable TCP/IP

Create Database User for Lambda Access

Allow Firewall Access

Find Your IP Address

Step 2: LocalStack Pro Setup

Step 3: Create the `.env` File

Step 4: Start LocalStack

Step 5: Build and Deploy to LocalStack

Step 6: Configure `appsettings.Development.json`

Step 7: Run the Web App

Step 8: Verify Everything Works

Test an Export

Test Backup Project

Run Lambda Tests

Quick Start Checklist

Re-Deploying After Code Changes

Key File Locations

Troubleshooting

Webhook Notifications Not Working

Other Common Issues

Architecture & Setup

Standards & Reference

​Prerequisites

Docker Desktop

.NET 6.0 SDK

Terraform

LocalStack Pro

​Step 1: SQL Server Configuration

​Enable Mixed Mode Authentication

​Enable TCP/IP

​Create Database User for Lambda Access

​Allow Firewall Access

​Find Your IP Address

​Step 2: LocalStack Pro Setup

​Step 3: Create the .env File

​Step 4: Start LocalStack

​Step 5: Build and Deploy to LocalStack

​Step 6: Configure appsettings.Development.json

​Step 7: Run the Web App

​Step 8: Verify Everything Works

​Test an Export

​Test Backup Project

​Run Lambda Tests

​Quick Start Checklist

​Re-Deploying After Code Changes

​Key File Locations

​Troubleshooting

​Webhook Notifications Not Working

​Other Common Issues

Prerequisites

Step 1: SQL Server Configuration

Enable Mixed Mode Authentication

Enable TCP/IP

Create Database User for Lambda Access

Allow Firewall Access

Find Your IP Address

Step 2: LocalStack Pro Setup

Step 3: Create the `.env` File

Step 4: Start LocalStack

Step 5: Build and Deploy to LocalStack

Step 6: Configure `appsettings.Development.json`

Step 7: Run the Web App

Step 8: Verify Everything Works

Test an Export

Test Backup Project

Run Lambda Tests

Quick Start Checklist

Re-Deploying After Code Changes

Key File Locations

Troubleshooting

Webhook Notifications Not Working

Other Common Issues