tutorials/local-setup.md

Local Development Setup Guide

This guide provides comprehensive instructions for setting up the Acsis Core Dynaplex architecture on your local development machine.

🎯 Overview

Local development with Dynaplex requires:

.NET 9.0 SDK for service development
Docker Desktop for infrastructure services
SQL Server for data persistence
Redis for caching (optional)
Node.js for UI development

💻 System Requirements

Minimum Requirements

Component	Requirement
OS	Windows 11, macOS 12+, Ubuntu 20.04+
RAM	16 GB
CPU	4 cores
Disk	50 GB free space
Docker	4 GB allocated

Recommended Requirements

Component	Requirement
OS	Latest stable version
RAM	32 GB
CPU	8 cores
Disk	100 GB SSD
Docker	8 GB allocated

🛠️ Prerequisites Installation

Windows

# Install Chocolatey (if not installed)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install prerequisites
choco install dotnet-sdk nodejs docker-desktop git visualstudio2022 -y

# Install SQL Server Developer Edition
choco install sql-server-express -y

# Install Redis (optional)
choco install redis-64 -y

# Install development tools
dotnet tool install -g Microsoft.OpenApi.Kiota
dotnet tool install -g dotnet-ef

macOS

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install prerequisites
brew install --cask dotnet-sdk
brew install node
brew install --cask docker
brew install git
brew install --cask visual-studio-code
brew install --cask rider  # Alternative to Visual Studio

# Install Azure Data Studio for SQL management
brew install --cask azure-data-studio

# Install development tools
dotnet tool install -g Microsoft.OpenApi.Kiota
dotnet tool install -g dotnet-ef

# For SQL Server on Mac, use Docker (see Docker Setup section)

Linux (Ubuntu/Debian)

# Add Microsoft package 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-9.0

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install Docker
sudo apt-get install -y docker.io docker-compose
sudo usermod -aG docker $USER

# Install Git
sudo apt-get install -y git

# Install development tools
dotnet tool install -g Microsoft.OpenApi.Kiota
dotnet tool install -g dotnet-ef

🐳 Docker Setup

Docker Compose Configuration

Create docker-compose.local.yml:

version: '3.8'

services:
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2022-latest
    container_name: acsis-sqlserver
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrong@Passw0rd
      - MSSQL_PID=Developer
    ports:
      - "1433:1433"
    volumes:
      - sqlserver-data:/var/opt/mssql
    networks:
      - acsis-network

  redis:
    image: redis:7-alpine
    container_name: acsis-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    networks:
      - acsis-network

  seq:
    image: datalust/seq:latest
    container_name: acsis-seq
    environment:
      - ACCEPT_EULA=Y
    ports:
      - "5341:80"
      - "45341:45341"
    volumes:
      - seq-data:/data
    networks:
      - acsis-network

  jaeger:
    image: jaegertracing/all-in-one:latest
    container_name: acsis-jaeger
    ports:
      - "16686:16686"  # Jaeger UI
      - "4317:4317"    # OTLP gRPC
      - "4318:4318"    # OTLP HTTP
    environment:
      - COLLECTOR_OTLP_ENABLED=true
    networks:
      - acsis-network

  prometheus:
    image: prom/prometheus:latest
    container_name: acsis-prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
    networks:
      - acsis-network

  grafana:
    image: grafana/grafana:latest
    container_name: acsis-grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
      - GF_INSTALL_PLUGINS=redis-datasource
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana/dashboards:/etc/grafana/provisioning/dashboards
      - ./grafana/datasources:/etc/grafana/provisioning/datasources
    networks:
      - acsis-network

volumes:
  sqlserver-data:
  redis-data:
  seq-data:
  prometheus-data:
  grafana-data:

networks:
  acsis-network:
    driver: bridge

Starting Docker Services

# Start all services
docker-compose -f docker-compose.local.yml up -d

# Check service status
docker-compose -f docker-compose.local.yml ps

# View logs
docker-compose -f docker-compose.local.yml logs -f

# Stop services
docker-compose -f docker-compose.local.yml down

# Stop and remove volumes (full reset)
docker-compose -f docker-compose.local.yml down -v

🗄️ Database Setup

Initial Database Creation

# Connect to SQL Server
docker exec -it acsis-sqlserver /opt/mssql-tools/bin/sqlcmd \
  -S localhost -U SA -P 'YourStrong@Passw0rd'

# Create database
CREATE DATABASE AcsisCore;
GO

USE AcsisCore;
GO

# Create schema for each component
CREATE SCHEMA CoreData;
GO
CREATE SCHEMA Identity;
GO
CREATE SCHEMA Catalog;
GO
CREATE SCHEMA Workflow;
GO

# Create a development user
CREATE LOGIN dev_user WITH PASSWORD = 'DevPassword123!';
CREATE USER dev_user FOR LOGIN dev_user;
ALTER ROLE db_owner ADD MEMBER dev_user;
GO

EXIT

Run Database Migrations

# Navigate to each component's DbMigrator
cd engines/core-data/src/Acsis.Dynaplex.Engines.CoreData.DbMigrator
dotnet run

cd engines/identity/src/Acsis.Dynaplex.Engines.Identity.DbMigrator
dotnet run

cd engines/catalog/src/Acsis.Dynaplex.Engines.Catalog.DbMigrator
dotnet run

# Or run all migrations via Aspire
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

⚙️ Configuration

User Secrets Setup

# Initialize user secrets for each service
cd engines/core-data/src/Acsis.Dynaplex.Engines.CoreData
dotnet user-secrets init

# Set connection string
dotnet user-secrets set "ConnectionStrings:Default" \
  "Server=localhost,1433;Database=AcsisCore;User Id=dev_user;Password=DevPassword123!;TrustServerCertificate=true"

# Set Redis connection
dotnet user-secrets set "ConnectionStrings:Redis" "localhost:6379"

# Set JWT signing key
dotnet user-secrets set "Jwt:SigningKey" "ThisIsADevelopmentKeyThatShouldBeAtLeast256BitsLong!"

# Set API keys
dotnet user-secrets set "ExternalApis:SapApiKey" "dev-sap-key"
dotnet user-secrets set "ExternalApis:MapsApiKey" "dev-maps-key"

Environment Variables

Create .env file in repository root:

# Database
DB_CONNECTION="Server=localhost,1433;Database=AcsisCore;User Id=dev_user;Password=DevPassword123!;TrustServerCertificate=true"

# Redis
REDIS_CONNECTION="localhost:6379"

# JWT
JWT_ISSUER="https://localhost:7061"
JWT_AUDIENCE="acsis-api"
JWT_SIGNING_KEY="ThisIsADevelopmentKeyThatShouldBeAtLeast256BitsLong!"

# Aspire
ASPIRE_ALLOW_UNSECURED_TRANSPORT="true"
DOTNET_ENVIRONMENT="Development"

# OpenTelemetry
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
OTEL_SERVICE_NAME="acsis-dev"

# Logging
SEQ_URL="http://localhost:5341"

appsettings.Development.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore": "Information"
    }
  },
  "AllowedHosts": "*",
  "Cors": {
    "AllowedOrigins": [
      "http://localhost:3000",
      "http://localhost:3001",
      "https://localhost:7061"
    ]
  },
  "FeatureFlags": {
    "EnableSwagger": true,
    "EnableMetrics": true,
    "EnableTracing": true,
    "UseMockExternalServices": true
  },
  "RateLimiting": {
    "PermitLimit": 1000,
    "Window": "00:01:00"
  }
}

🚀 Running the Application

Method 1: Using .NET Aspire (Recommended)

# Build everything
dotnet build acsis-core.slnx

# Run Aspire AppHost
dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/

# The Aspire dashboard will open automatically
# Services available at:
# - Aspire Dashboard: http://localhost:15045
# - CoreData API: https://localhost:40443/scalar
# - Catalog API: https://localhost:43443/scalar
# - Identity API: https://localhost:41443/scalar

Method 2: Running Individual Services

# Terminal 1: Core Data Service
cd engines/core-data/src/Acsis.Dynaplex.Engines.CoreData
dotnet run --urls="https://localhost:40443;http://localhost:40080"

# Terminal 2: Identity Service
cd engines/identity/src/Acsis.Dynaplex.Engines.Identity
dotnet run --urls="https://localhost:41443;http://localhost:41080"

# Terminal 3: Catalog Service
cd engines/catalog/src/Acsis.Dynaplex.Engines.Catalog
dotnet run --urls="https://localhost:43443;http://localhost:43080"

# Terminal 4: UI
cd engines/assettrak-ui/src/acsis-assettrak-ui
npm install
npm run dev

Method 3: Using Tye (Alternative to Aspire)

# Install Tye
dotnet tool install -g Microsoft.Tye --version "0.11.0-*"

# Create tye.yaml
tye init

# Run with Tye
tye run

# Dashboard available at: http://localhost:8000

🧪 Running Tests

# Run all tests
dotnet test acsis-core.slnx

# Run with coverage
dotnet test --collect:"XPlat Code Coverage" --results-directory ./TestResults

# Run specific test project
dotnet test engines/core-data/test/Acsis.Dynaplex.Engines.CoreData.Tests/

# Run integration tests (requires services running)
dotnet test --filter Category=Integration

# Run with detailed output
dotnet test --logger "console;verbosity=detailed"

🔍 Debugging

Visual Studio 2022

Open acsis-core.slnx
Set Acsis.Dynaplex.Projects.BbuRfid as startup project
Press F5 to run with debugging
Set breakpoints in any service

Visual Studio Code

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Aspire AppHost",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${workspaceFolder}/projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/bin/Debug/net9.0/Acsis.Dynaplex.Projects.BbuRfid.dll",
      "args": [],
      "cwd": "${workspaceFolder}/projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid",
      "console": "internalConsole",
      "stopAtEntry": false,
      "env": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    {
      "name": "Attach to Process",
      "type": "coreclr",
      "request": "attach",
      "processId": "${command:pickProcess}"
    }
  ],
  "compounds": [
    {
      "name": "Debug All Services",
      "configurations": [
        "CoreData Service",
        "Identity Service",
        "Catalog Service"
      ]
    }
  ]
}

JetBrains Rider

Open acsis-core.slnx
Create compound run configuration
Add each service project
Enable "Allow parallel run"
Start debugging with Shift+F9

🛠️ Common Development Tasks

Adding a New Component

# Use the Dynaplex CLI
dotnet new dplx-component -n MyComponent

# Or manually
mkdir -p engines/my-component/src
cd engines/my-component/src

# Create projects
dotnet new classlib -n Acsis.Dynaplex.Engines.MyComponent.Abstractions
dotnet new webapi -n Acsis.Dynaplex.Engines.MyComponent
dotnet new classlib -n Acsis.Dynaplex.Engines.MyComponent.ApiClient
dotnet new console -n Acsis.Dynaplex.Engines.MyComponent.DbMigrator

# Add to solution
dotnet sln ../../acsis-core.slnx add **/*.csproj

Regenerating API Clients

# Update OpenAPI spec first
cd engines/my-component/src/Acsis.Dynaplex.Engines.MyComponent
# Edit openapi.yaml

# Generate client
cd ../Acsis.Dynaplex.Engines.MyComponent.ApiClient
kiota generate \
  --language csharp \
  --openapi ../Acsis.Dynaplex.Engines.MyComponent/openapi.yaml \
  --output ./Generated \
  --namespace Acsis.Dynaplex.Engines.MyComponent.ApiClient

Database Migration

# Add migration
cd engines/my-component/src/Acsis.Dynaplex.Engines.MyComponent
dotnet ef migrations add InitialCreate \
  --project ../Acsis.Dynaplex.Engines.MyComponent.DbMigrator \
  --context MyComponentContext

# Update database
dotnet ef database update \
  --project ../Acsis.Dynaplex.Engines.MyComponent.DbMigrator \
  --context MyComponentContext

🔧 Troubleshooting

Port Conflicts

# Find process using port
# Windows
netstat -ano | findstr :40443
taskkill /F /PID <PID>

# macOS/Linux
lsof -i :40443
kill -9 <PID>

# Change ports in launchSettings.json if needed

Database Connection Issues

# Test SQL Server connection
docker exec -it acsis-sqlserver /opt/mssql-tools/bin/sqlcmd \
  -S localhost -U SA -P 'YourStrong@Passw0rd' -Q "SELECT 1"

# Check SQL Server logs
docker logs acsis-sqlserver

# Reset SQL Server
docker-compose -f docker-compose.local.yml restart sqlserver

Certificate Issues (HTTPS)

# Trust development certificate
dotnet dev-certs https --clean
dotnet dev-certs https --trust

# For macOS
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  ~/.dotnet/corefx/cryptography/x509stores/my/*.pfx

Memory Issues

# Increase Docker memory (Docker Desktop settings)
# Recommended: 8GB minimum

# Clear Docker resources
docker system prune -a --volumes

# Limit service memory in docker-compose.yml
services:
  sqlserver:
    mem_limit: 2g

📊 Monitoring Local Development

Health Checks

# Check all services health
curl http://localhost:15045/health

# Individual service health
curl https://localhost:40443/health
curl https://localhost:41443/health
curl https://localhost:43443/health

Logs

# View Aspire logs
# Automatically shown in Aspire dashboard

# View Docker logs
docker-compose -f docker-compose.local.yml logs -f

# View Seq logs (structured)
open http://localhost:5341

Metrics

# Prometheus metrics
open http://localhost:9090

# Grafana dashboards
open http://localhost:3000
# Default login: admin/admin

# Jaeger traces
open http://localhost:16686

🚄 Performance Optimization

Local Performance Tips

Use SSD: Store code and Docker volumes on SSD
Allocate Resources: Give Docker at least 4GB RAM
Disable Unnecessary Services: Only run required services
Use Caching: Enable Redis for better performance
Optimize Queries: Use SQL Server Profiler for slow queries

Development Shortcuts

# Create aliases for common commands
alias aspire="dotnet run --project projects/bbu-rfid/src/Acsis.Dynaplex.Projects.BbuRfid/"
alias build-all="dotnet build acsis-core.slnx"
alias test-all="dotnet test acsis-core.slnx"
alias docker-up="docker-compose -f docker-compose.local.yml up -d"
alias docker-down="docker-compose -f docker-compose.local.yml down"

🔄 Keeping Environment Updated

# Update .NET SDK
dotnet --list-sdks
# Download latest from https://dotnet.microsoft.com

# Update Node.js
npm install -g n
n latest

# Update Docker images
docker-compose -f docker-compose.local.yml pull

# Update NuGet packages
dotnet list package --outdated
dotnet add package <package-name>

# Update npm packages
cd engines/assettrak-ui/src/acsis-assettrak-ui
npm update
npm audit fix

Documentation