Skip to main content
This guide provides detailed instructions for installing, configuring, and deploying SAPFIAI in various environments.

​
System Requirements

​
Minimum Requirements

.NET 8.0 SDK

Required for building and running the application

Database Server

SQL Server 2019+, LocalDB, Express, or SQLite

IDE

Visual Studio 2022+ or VS Code with C# extension

Git

Version control for cloning the repository
  • OS: Windows 10/11, macOS 12+, or Linux (Ubuntu 20.04+)
  • RAM: 8 GB minimum, 16 GB recommended
  • Storage: 2 GB for dependencies and build artifacts
  • CPU: 64-bit processor, 2+ cores recommended

​
Prerequisites Installation

1

Install .NET 8.0 SDK

Download and install the .NET 8.0 SDK from the official website:Download .NET 8.0 SDKVerify the installation:
dotnet --version
Expected output: 8.0.x
# Using winget (Windows Package Manager)
winget install Microsoft.DotNet.SDK.8

# Or download and run the installer from microsoft.com
2

Install Database Server

Choose one of the following database options:
Download from Microsoft: SQL Server ExpressAfter installation, verify the service is running:
# Check SQL Server service status
sc query MSSQL$SQLEXPRESS
Use Docker to run SQL Server on non-Windows platforms:
# Pull SQL Server 2022 image
docker pull mcr.microsoft.com/mssql/server:2022-latest

# Run SQL Server container
docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=YourStrong@Password" \
  -p 1433:1433 --name sqlserver \
  -d mcr.microsoft.com/mssql/server:2022-latest

# Verify it's running
docker ps
Connection string:
"DefaultConnection": "Server=localhost,1433;Database=SAPFIAIDb;User Id=sa;Password=YourStrong@Password;TrustServerCertificate=true"
No installation required! SQLite is embedded and works on all platforms.Just use a SQLite connection string:
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=sapfiai.db"
  }
}
SQLite is great for development and testing but not recommended for production with high concurrency.
3

Install Development Tools

Choose your preferred development environment:
Download from: VS Code DownloadsRequired Extensions:
# Install via command line
code --install-extension ms-dotnettools.csharp
code --install-extension ms-dotnettools.csdevkit
code --install-extension jchannon.csharpextensions
code --install-extension formulahendry.dotnet-test-explorer
Or search in VS Code Extensions:
  • C# (Microsoft)
  • C# Dev Kit (Microsoft)
  • NuGet Package Manager
  • REST Client
Download from: JetBrains RiderRider has built-in support for .NET, EF Core, and all required features.
4

Install Entity Framework Core Tools

Install the EF Core command-line tools globally:
dotnet tool install --global dotnet-ef
Verify installation:
dotnet ef --version
If you already have dotnet-ef installed, update it:
dotnet tool update --global dotnet-ef
5

Install Git (Optional but Recommended)

Download from: Git DownloadsVerify installation:
git --version

​
Project Setup

1

Clone or Download the Project

Option 1: Clone with Git
git clone <repository-url>
cd SAPFIAI
Option 2: Download ZIP
  • Download the project ZIP file
  • Extract to your desired location
  • Open terminal in the extracted folder
2

Restore NuGet Packages

Restore all project dependencies:
dotnet restore
This downloads:
  • ASP.NET Core 8.0 packages
  • Entity Framework Core 8.0
  • MediatR, AutoMapper, FluentValidation
  • Testing frameworks (NUnit, Moq, FluentAssertions)
  • All other dependencies
First restore might take 2-5 minutes depending on your internet connection.
3

Build the Solution

Verify the project builds successfully:
dotnet build
Expected output:
Build succeeded.
    0 Warning(s)
    0 Error(s)
Issue: SDK Version Mismatch
error NETSDK1045: The current .NET SDK does not support targeting .NET 8.0
Solution: Install .NET 8.0 SDKIssue: Package Restore Failed
error NU1101: Unable to find package
Solution:
dotnet nuget locals all --clear
dotnet restore --force

​
Configuration

1

Configure Database Connection

Edit src/Web/appsettings.json and update the connection string:
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=SAPFIAIDb;Trusted_Connection=true;MultipleActiveResultSets=true"
  }
}
Never commit actual passwords to version control! Use environment variables or user secrets for production.
2

Configure JWT Authentication

Update JWT settings in src/Web/appsettings.json:
{
  "Jwt": {
    "Key": "YOUR-SUPER-SECRET-KEY-MINIMUM-32-CHARACTERS-LONG-CHANGE-THIS",
    "Issuer": "SAPFIAI",
    "Audience": "SAPFIAI-Users",
    "ExpireMinutes": "60",
    "RefreshTokenExpirationDays": "7"
  }
}
  • Key: Must be at least 32 characters. Use a strong random string.
  • ExpireMinutes: Access token lifetime (recommended: 15-60 minutes)
  • RefreshTokenExpirationDays: Refresh token lifetime (recommended: 7-30 days)
Generate a secure key:
# Using PowerShell
[Convert]::ToBase64String((1..64 | ForEach-Object { Get-Random -Maximum 256 }))

# Using OpenSSL
openssl rand -base64 64
3

Configure Security Settings (Optional)

Adjust security thresholds in src/Web/appsettings.json:
{
  "Security": {
    "RefreshToken": {
      "ExpirationDays": 7,
      "MaxActiveTokensPerUser": 5
    },
    "RateLimiting": {
      "MaxAttemptsPerIp": 5,
      "WindowMinutes": 15,
      "IpBlockDurationMinutes": 60
    },
    "AccountLock": {
      "MaxFailedAttempts": 5,
      "LockoutMinutes": 15,
      "ResetFailedAttemptsAfterMinutes": 60
    },
    "BlackList": {
      "EnableAutoBlock": true,
      "AutoBlockAfterAttempts": 10,
      "AutoBlockDurationHours": 24
    }
  }
}
Refresh Token:
  • ExpirationDays: How long refresh tokens are valid
  • MaxActiveTokensPerUser: Limit concurrent sessions per user
Rate Limiting:
  • MaxAttemptsPerIp: Login attempts allowed per IP
  • WindowMinutes: Time window for counting attempts
  • IpBlockDurationMinutes: Temporary block duration
Account Lock:
  • MaxFailedAttempts: Failed logins before account lockout
  • LockoutMinutes: Account lockout duration
  • ResetFailedAttemptsAfterMinutes: When to reset failure counter
IP Blacklist:
  • EnableAutoBlock: Automatically block abusive IPs
  • AutoBlockAfterAttempts: Attempts before auto-block
  • AutoBlockDurationHours: Auto-block duration
4

Use User Secrets for Development (Recommended)

Instead of storing sensitive data in appsettings.json, use User Secrets:
cd src/Web

# Initialize user secrets
dotnet user-secrets init

# Set connection string
dotnet user-secrets set "ConnectionStrings:DefaultConnection" "Server=(localdb)\\mssqllocaldb;Database=SAPFIAIDb;Trusted_Connection=true;"

# Set JWT key
dotnet user-secrets set "Jwt:Key" "YOUR-SUPER-SECRET-KEY-HERE"

# List all secrets
dotnet user-secrets list
User secrets are stored outside the project directory and are never committed to version control.
5

Configure Email Service (Optional)

If you want to enable email features (2FA, password reset), configure an email provider.SAPFIAI includes Brevo (formerly SendinBlue) integration:
{
  "Brevo": {
    "ApiKey": "xkeysib-your-api-key-here",
    "SenderEmail": "[email protected]",
    "SenderName": "SAPFIAI"
  }
}
Using User Secrets:
dotnet user-secrets set "Brevo:ApiKey" "xkeysib-your-key"
dotnet user-secrets set "Brevo:SenderEmail" "[email protected]"
SAPFIAI works with any SMTP provider. Popular options:
  • Brevo (included): Free tier available, easy integration
  • SendGrid: 100 emails/day free
  • Mailgun: 5,000 emails/month free
  • AWS SES: Pay-as-you-go pricing
  • Custom SMTP: Use your own mail server

​
Database Migration

1

Apply Database Migrations

Create the database and apply all migrations:
dotnet ef database update --project src/Infrastructure --startup-project src/Web
This will:
  1. Create the SAPFIAIDb database
  2. Create all tables (AspNetUsers, RefreshTokens, Permissions, etc.)
  3. Apply initial data seeding
Build started...
Build succeeded.
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (85ms) [Parameters=[], CommandType='Text']
      CREATE DATABASE [SAPFIAIDb];
info: Microsoft.EntityFrameworkCore.Database.Command[20101]
      Executed DbCommand (12ms) [Parameters=[], CommandType='Text']
      CREATE TABLE [AspNetUsers] (
          [Id] nvarchar(450) NOT NULL,
          [UserName] nvarchar(256) NULL,
          [Email] nvarchar(256) NULL,
          ...
      );
Done.
2

Verify Database Creation

Connect to your database and verify tables were created:Using SQL Server Management Studio (SSMS):
  • Server: (localdb)\mssqllocaldb
  • Database: SAPFIAIDb
Using command line:
sqlcmd -S "(localdb)\\mssqllocaldb" -d SAPFIAIDb -Q "SELECT name FROM sys.tables"
Expected tables:
  • AspNetUsers, AspNetRoles, AspNetUserRoles
  • RefreshTokens
  • LoginAttempts
  • IpBlackLists
  • AuditLogs
  • Permissions, RolePermissions
3

Seed Initial Data (Optional)

The application automatically seeds:
  • Default administrator role
  • Basic permissions
  • System configuration
To create an admin user, run the application and register via API, then manually assign the admin role in the database.
After registering a user via the API:
-- Get user ID
SELECT Id, UserName, Email FROM AspNetUsers WHERE Email = '[email protected]';

-- Get admin role ID
SELECT Id, Name FROM AspNetRoles WHERE Name = 'Administrator';

-- Assign admin role to user
INSERT INTO AspNetUserRoles (UserId, RoleId)
VALUES ('user-id-here', 'role-id-here');

​
Running the Application

1

Start the API Server

Run the application:
dotnet run --project src/Web
Or with hot reload:
dotnet watch run --project src/Web
From Visual Studio:
  • Open SAPFIAI.sln
  • Press F5 or click the green play button
  • Select “Web” profile if prompted
2

Verify the Application is Running

Check the console output for the URLs:
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
Navigate to:
3

Test Basic Functionality

Make a test request:
# Health check
curl https://localhost:5001/health

# Expected: "Healthy"
Or open Swagger UI and try the /api/Authentication/register endpoint.

​
Production Deployment

1

Update Production Configuration

Create src/Web/appsettings.Production.json:
{
  "ConnectionStrings": {
    "DefaultConnection": "Server=production-server;Database=SAPFIAIDb;User Id=app_user;Password=secure_password;Encrypt=true;"
  },
  "Jwt": {
    "Key": "USE-ENVIRONMENT-VARIABLE-OR-KEY-VAULT",
    "ExpireMinutes": "15"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}
Never store production secrets in configuration files! Use:
  • Azure Key Vault
  • AWS Secrets Manager
  • Environment variables
  • Container secrets
2

Publish the Application

Create a production build:
dotnet publish src/Web/Web.csproj -c Release -o ./publish
This creates a deployment-ready package in the ./publish folder.
3

Apply Production Migrations

Option 1: Generate SQL Script
dotnet ef migrations script --project src/Infrastructure --startup-project src/Web --output migration.sql
Execute the script on your production database.Option 2: Run Migrations on Startup Enable in Program.cs (not recommended for production):
if (app.Environment.IsProduction())
{
    await app.InitialiseDatabaseAsync();
}
4

Deploy to Hosting Platform

# Install Azure CLI
az login

# Create resource group
az group create --name sapfiai-rg --location eastus

# Create App Service plan
az appservice plan create --name sapfiai-plan --resource-group sapfiai-rg --sku B1 --is-linux

# Create web app
az webapp create --name sapfiai-api --resource-group sapfiai-rg --plan sapfiai-plan --runtime "DOTNETCORE:8.0"

# Deploy
az webapp up --name sapfiai-api --resource-group sapfiai-rg --src-path ./publish
Create Dockerfile in project root:
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["src/Web/Web.csproj", "src/Web/"]
COPY ["src/Application/Application.csproj", "src/Application/"]
COPY ["src/Infrastructure/Infrastructure.csproj", "src/Infrastructure/"]
COPY ["src/Domain/Domain.csproj", "src/Domain/"]
RUN dotnet restore "src/Web/Web.csproj"
COPY . .
WORKDIR "/src/src/Web"
RUN dotnet build "Web.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "Web.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "Web.dll"]
Build and run:
docker build -t sapfiai-api .
docker run -p 8080:80 sapfiai-api
  1. Install .NET 8.0 Hosting Bundle
  2. Create IIS Application Pool (.NET CLR Version: No Managed Code)
  3. Create IIS Website pointing to ./publish folder
  4. Configure web.config (auto-generated by publish)
  5. Set Application Pool identity to access SQL Server
  6. Restart IIS

​
Troubleshooting

Symptoms: Can’t connect to databaseSolutions:
  1. Verify SQL Server is running: 
    sqllocaldb info
sqllocaldb start MSSQLLocalDB
  2. Test connection string: 
    sqlcmd -S "(localdb)\\mssqllocaldb" -Q "SELECT @@VERSION"
  3. Check firewall rules (for remote SQL Server)
  4. Enable TCP/IP in SQL Server Configuration Manager
Symptoms: dotnet ef database update failsSolutions:
  1. Verify EF Core tools are installed: 
    dotnet ef --version
  2. Drop and recreate database: 
    dotnet ef database drop --project src/Infrastructure --startup-project src/Web
dotnet ef database update --project src/Infrastructure --startup-project src/Web
  3. Check for migration conflicts: 
    dotnet ef migrations list --project src/Infrastructure --startup-project src/Web
Symptoms: “Unauthorized” errors or invalid tokensSolutions:
  1. Verify JWT key is at least 32 characters
  2. Check token expiration settings
  3. Ensure clock synchronization (server time)
  4. Verify Issuer and Audience match in settings
Symptoms: Browser shows certificate warningsSolution:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Restart your browser after trusting the certificate.
Symptoms: “Address already in use” errorSolutions:
  1. Change ports in launchSettings.json
  2. Find and kill the process using the port: 
    # Windows
netstat -ano | findstr :5001
taskkill /PID <process-id> /F

# Linux/macOS
lsof -ti:5001 | xargs kill -9

​
Next Steps

Your SAPFIAI installation is complete! Explore these resources:

Quickstart Guide

Get your API running quickly

Architecture Guide

Understand the project structure

API Reference

Explore available endpoints

Creating Use Cases

Learn how to add new features

Build docs developers (and LLMs) love

Get started for freeTalk to us