Setup Guide

Step-by-step from the source archive to a running, signed-in application. Cross-platform notes called out where they matter; defaults assume Windows (since the project path is D:\AssetTrackingSystem).

If you've never touched .NET or Angular: this guide covers the full path. If you've already shipped .NET + Angular apps before, jump to Quick start (TL;DR).

Quick start (TL;DR)

# 1. Download and extract the source archive (e.g. AssetTrackingSystem.zip)
#    Resulting folder: AssetTrackingSystem/
cd AssetTrackingSystem

# 2. Install SQL Server locally (skip if already running)
#    Windows: SQL Server Express + SSMS, OR Docker. See §3.

# 3. Configure the connection string in src/AssetTracking.API/appsettings.json
#    Default points at the local Windows-auth instance "Server=.;Database=AssetTracking"

# 4. Backend
dotnet restore
dotnet ef database update --project src/AssetTracking.Persistence --startup-project src/AssetTracking.API

# 5. Frontend
cd frontend && npm install && cd ..

# 6. Run (two terminals)
dotnet run --project src/AssetTracking.API   # terminal 1 (backend)
cd frontend && npm start                     # terminal 2 (frontend)

# 7. Open http://localhost:4200
#    Sign in: admin@assettracking.local / Admin@123456

If any of those steps are unfamiliar, the rest of this doc walks each in detail.

Index

1. Prerequisites
2. Get the source code
3. Set up SQL Server
4. Configure the API
5. Restore and build the backend
6. Apply database migrations
7. Set up the frontend
8. Run the API
9. Run the frontend dev server
10. Sign in for the first time
11. Optional configuration
12. Troubleshooting

1. Prerequisites

Install these once before starting:

Verify each:

dotnet --version       # should print 8.0.x
node --version         # v18.x or v20.x
npm --version          # 9.x or higher
dotnet ef --version    # 8.0.x

If dotnet ef returns "command not found", run the install command from the table above. The Path may need a shell restart afterwards.

Recommended (optional)

• Visual Studio 2022 (Community is free) or Rider for a friendly C# debugger experience. The project also works fine with VS Code + C# Dev Kit.
• SQL Server Management Studio (SSMS) for poking at the database. Free.
• Postman or Insomnia for hitting the API directly while testing.

2. Get the source code

The source is delivered as a zip archive (e.g. AssetTrackingSystem.zip) via download link.

1. Download the archive to a working location — e.g. D:\AssetTrackingSystem.zip on Windows or ~/AssetTrackingSystem.zip on macOS/Linux.

2. Extract it. On Windows, right-click → Extract All... (or use 7-Zip / WinRAR). On macOS/Linux: unzip AssetTrackingSystem.zip.

3. Open a terminal in the extracted folder:

   cd AssetTrackingSystem
   

You should now have:

AssetTrackingSystem/
├── AssetTracking.slnx          ← solution file
├── docs/                       ← all documentation
├── src/
│   ├── AssetTracking.API/
│   ├── AssetTracking.Application/
│   ├── AssetTracking.Domain/
│   ├── AssetTracking.Infrastructure/
│   └── AssetTracking.Persistence/
├── tests/
└── frontend/

3. Set up SQL Server

You need one of these options running before the API can connect.

Option A — Local SQL Server Express (Windows, easiest)

1. Download SQL Server Express from https://www.microsoft.com/sql-server/sql-server-downloads.
2. Choose Basic install. Accept the default instance name (SQLEXPRESS or default MSSQLSERVER).
3. Optionally install SSMS for a GUI.

The connection string in appsettings.json ships pointing at the default instance (Server=.). If you installed SQLEXPRESS instead of the default instance, you'll need to update the connection string in §4.

Option B — SQL Server Developer Edition

Same as Express, but unlimited capacity (free for non-production).

Option C — LocalDB (Windows, lightweight)

Comes with Visual Studio. No service to manage. Connection string:

Server=(localdb)\\MSSQLLocalDB;Database=AssetTracking;Trusted_Connection=True;TrustServerCertificate=True

Option D — Docker (cross-platform — Mac, Linux, also fine on Windows)

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=Strong@Passw0rd" \
  -p 1433:1433 --name mssql -d mcr.microsoft.com/mssql/server:2022-latest

Then connect with:

Server=localhost,1433;Database=AssetTracking;User ID=sa;Password=Strong@Passw0rd;TrustServerCertificate=True

(Pick a stronger password than the example. Add a volume mount for persistence: -v mssql-data:/var/opt/mssql.)

Verify the connection

From the command line:

# If you have sqlcmd installed:
sqlcmd -S . -E -Q "SELECT @@VERSION"        # Windows-auth
sqlcmd -S localhost,1433 -U sa -P Strong@Passw0rd -Q "SELECT @@VERSION"  # SQL-auth

Or open SSMS / Azure Data Studio and connect with the same credentials.

You don't need to create the AssetTracking database manually. EF Core will create it when migrations run in §6.

4. Configure the API

Open src/AssetTracking.API/appsettings.json. The defaults look like this:

{
  "ConnectionStrings": {
    "SqlServer": "Server=.;Database=AssetTracking;Trusted_Connection=True;TrustServerCertificate=True;MultipleActiveResultSets=true"
  },
  "JwtSettings": {
    "Secret": "YourSuperSecretKeyThatIsAtLeast32CharactersLong!!",
    "Issuer": "AssetTracking",
    "Audience": "AssetTrackingClients",
    "AccessTokenExpirationMinutes": 15,
    "RefreshTokenExpirationDays": 30
  },
  "Cors": { "AllowedOrigins": [ "http://localhost:4200" ] },
  "FileStorage": { "RootPath": "AppData/Documents" },
  "Seeding": {
    "HierarchyConfigs": true,
    "WorkflowRoles": true,
    "DemoUsers": true
  }
}

What to change

Always

• ConnectionStrings:SqlServer — point this at the SQL Server instance you set up in §3. Common variations:

  Setup	Connection string
  Default instance, Windows auth (default)	Server=.;Database=AssetTracking;Trusted_Connection=True;TrustServerCertificate=True;MultipleActiveResultSets=true
  SQL Server Express	Server=.\\SQLEXPRESS;Database=AssetTracking;Trusted_Connection=True;TrustServerCertificate=True
  LocalDB	Server=(localdb)\\MSSQLLocalDB;Database=AssetTracking;Trusted_Connection=True;TrustServerCertificate=True
  Docker (sa user)	Server=localhost,1433;Database=AssetTracking;User ID=sa;Password=Strong@Passw0rd;TrustServerCertificate=True

For production (or any non-local environment)

• JwtSettings:Secret — generate a fresh random string at least 32 characters. Don't ship the default secret to anything reachable from the internet. A quick way:

  # PowerShell:
  -join ((48..57) + (65..90) + (97..122) | Get-Random -Count 64 | % {[char]$_})
  
  # Linux / macOS:
  head -c 64 /dev/urandom | base64
  

• Cors:AllowedOrigins — add the URL where the SPA will be served. The default http://localhost:4200 is the Angular dev server.

For development (defaults are fine)

• JwtSettings:AccessTokenExpirationMinutes (15) and RefreshTokenExpirationDays (30) — leave alone unless you have a security policy.
• FileStorage:RootPath — relative to the API process working directory. Created automatically. Make sure the process can write there.
• Seeding flags — see §10 / §11. Leave all true for the default demo experience.

Production secret management

For production, don't put secrets in appsettings.json. Standard ASP.NET Core layering applies — override via:

• Environment variables: JwtSettings__Secret=... (note double underscores)
• appsettings.Production.json
• dotnet user-secrets (development only)
• Whatever your hosting provider uses (Azure Key Vault, AWS Secrets Manager, …)

5. Restore and build the backend

From the project root (the folder containing AssetTracking.slnx):

dotnet restore
dotnet build

Expected output ends with Build succeeded. and zero errors. Compilation should take 30-60 seconds on a first run; subsequent builds are seconds.

If the build fails, see Troubleshooting.

6. Apply database migrations

This creates the AssetTracking database (if it doesn't exist) and adds every table.

dotnet ef database update --project src/AssetTracking.Persistence --startup-project src/AssetTracking.API

Output should end with Done. (no errors).

Heads up — file lock. If the API process is running in another terminal, this command will fail with a MSB3027 "file is locked" error because EF can't recompile the API project while it's executing. Stop the running API first (Ctrl+C in its terminal), run the migration, then restart.

Verify

Connect with SSMS / Azure Data Studio / sqlcmd. You should see the AssetTracking database with ~50 tables (Users, Roles, Permissions, Assets, AuditPlans, …).

7. Set up the frontend

cd frontend
npm install

This downloads ~600 MB of packages (Angular, PrimeNG, Puppeteer's Chromium for tests, etc.). Allow 2-5 minutes on first run.

If npm install fails with peer-dependency conflicts, try:

npm install --legacy-peer-deps

(The project's package versions are tested as a known-good combination; the --legacy-peer-deps flag relaxes npm's strictness.)

8. Run the API

In a terminal at the project root:

dotnet run --project src/AssetTracking.API

Expected boot output (abridged):

[INF] Now listening on: https://localhost:5001
[INF] Now listening on: http://localhost:5000
[INF] Application started.

The API does three things on startup:

1. Applies any pending migrations (idempotent — safe to run repeatedly).
2. Runs the database seeder — inserts the permission catalog, the SuperAdmin role, the default admin user, the asset statuses, the notification templates, and (when Seeding.WorkflowRoles = true) the 10 workflow roles + (when Seeding.DemoUsers = true) 11 demo users.
3. Drops sample import templates into AppData/SampleData/ for organizations, locations, classifications, vendors, manufacturers, and assets — useful when testing the bulk-import features. (Skipped if the folder already has files.)

You can verify it's running by visiting http://localhost:5000/swagger in a browser (Development environment only). You should see the Swagger UI listing every endpoint.

9. Run the frontend dev server

In a second terminal:

cd frontend
npm start

Wait for:

✔ Compiled successfully.
Local:   http://localhost:4200/

The dev server proxies /api/* to the backend via frontend/proxy.conf.json (default target http://localhost:5000). So the SPA never sees a CORS problem in development.

If your API is running on a non-default port, update frontend/proxy.conf.json:

{
  "/api": {
    "target": "http://localhost:5000",
    "secure": false,
    "changeOrigin": true
  }
}

(Replace 5000 with your actual API port.)

10. Sign in for the first time

Open http://localhost:4200. You should land on the login page.

Default Super Admin credentials:

Sign in. You should land on the Dashboard with every nav group visible (because the Super Admin holds every permission).

Demo accounts (development only)

If you left Seeding.DemoUsers = true, ten more accounts are available with the shared password Demo@123456. Try them to see the system from each role's perspective:

Logging in as mobile@... automatically lands you at /mobile because that user has UserType = Mobile.

What to do next

1. Add some master data: at least one Organization, Location, and Classification. Use /organizations, /locations, /classifications — or import from the sample Excel files dropped into AppData/SampleData/.
2. Register a few assets at /assets. They need an Organization, Location, Classification, and Status.
3. Create your real users at /users and assign them roles.
4. Disable demo users before going live — see §11.

For deeper walkthroughs of every screen, see docs/business/04-features-by-module.

11. Optional configuration

Email (SMTP)

Outbound notifications need an SMTP server. Without configuration, in-app notifications still work — only emails are blocked.

Configure at runtime via the UI: log in as admin, go to Settings → Email Provider (/settings/email).

Fill in:

Click Send test email to a live address to verify.

Gmail-specific tip

A regular Gmail password won't work — Google blocks SMTP basic-auth. Generate an App Password:

1. https://myaccount.google.com/security → enable 2-Step Verification.
2. Go to App passwords → generate a new one (16 characters).
3. Paste that into the Password field.

Bilingual settings

The system is bilingual by design. Out of the box:

• Primary language = English (en)
• Secondary language = Arabic (ar)

If your deployment uses different languages (e.g., Spanish + English), change at Settings → App Languages (/settings/languages). Pick the two languages from the dropdown. The change is immediate and propagates across all users on their next page render.

UI translation overrides

The bundled translations cover English and Arabic completely; the other 9 languages have partial coverage. To customize labels (or fill in missing translations) without re-deploying:

Settings → Translations (/settings/translations). Pick a language tab, edit any cell, save. Reset clears the override. See docs/business/06-localization-and-rtl for the full editor walkthrough.

Hierarchy depth

Each of Organization / Location / Classification has a configurable depth and per-level labels.

Settings → Hierarchy (/settings/hierarchy). For Locations: e.g., 4 levels = Site / Building / Floor / Room. For Organizations: e.g., 3 levels = Company / Department / Team. Bilingual labels per level.

Disable demo users (production)

Before deploying to staging or production, edit appsettings.json:

"Seeding": {
  "HierarchyConfigs": true,
  "WorkflowRoles": true,
  "DemoUsers": false
}

The WorkflowRoles flag stays true so the seeded roles are still available for assigning to your real users. Setting DemoUsers = false skips creating the 11 demo accounts on subsequent restarts.

If demo users were already created on a prior boot, delete them manually at /users (the IsDeleted flag is sufficient for soft-delete) — the seeder doesn't remove existing demos when you flip the flag.

Change the admin password

Critical for production. Sign in as admin → Profile → Change password. Pick a strong unique password.

12. Troubleshooting

dotnet restore or dotnet build fails

• NuGet feed unreachable — check internet/firewall. Verify with dotnet nuget list source and add https://api.nuget.org/v3/index.json if missing.
• Wrong .NET SDK version — dotnet --version should be 8.0.x. The csproj files target net8.0.

dotnet ef database update fails

• "Could not connect to SQL Server" — your connection string is wrong or the SQL Server service isn't running. Verify with sqlcmd or SSMS.
• "Login failed for user 'X'" — credentials in the connection string are wrong, OR Windows-auth user lacks DB-create rights. Either fix permissions or switch to SQL-auth.
• "file is locked" — the API is running. Stop it first.
• "No DbContext was found" — make sure both --project and --startup-project flags are present.

npm install fails

• Peer-dependency conflicts — npm install --legacy-peer-deps.
• Network errors during Puppeteer / Chromium download — re-run npm install. Or set PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true if you don't need the PDF generation feature locally.
• Permission errors on Linux — don't use sudo npm install. Instead, install Node via nvm so it lives in your home directory.

npm start fails

• Port 4200 already in use — npm start -- --port 4201.
• Cannot find module 'X' — try rm -rf node_modules package-lock.json && npm install.
• Proxy error / ECONNREFUSED — the API isn't running on the port the proxy expects. Either start the API first, or update frontend/proxy.conf.json.

API starts but throws on first request

• "Migration not applied" — re-run dotnet ef database update.
• "Cannot open database" — connection-string database name doesn't exist. EF should create it on first migration; if it didn't, check permissions of the SQL login.
• CORS errors in browser console — your SPA origin isn't in Cors:AllowedOrigins. Add it to appsettings.json and restart the API.

Login page rejects the default credentials

• Seeder didn't run — check the API console output. Look for Seeded SuperAdmin user. If absent, the seeder may have errored. Check the connection string and re-run.
• Database is missing the Users table — migrations weren't applied. Run dotnet ef database update.
• Typo in the password — it's Admin@123456 (zero, not letter O; capital A; @ sign).

Camera doesn't work in the mobile shell

• Browser blocked the camera prompt — open browser settings → Site Permissions → allow camera for http://localhost:4200.
• Camera works on the system but the scanner area is black — a CSS quirk we already fixed. If the issue resurfaces after a code change, check that no descendant of .reader-wrap has background: #000 !important painting over the QR-box overlay.
• Running on a non-localhost HTTP origin — camera APIs are blocked on LAN-IP HTTP. Either use localhost or set up HTTPS.

"Another instance with the same key value is already being tracked"

This was a known bug pattern. Every handler that adds multiple child entities sets Id = Guid.NewGuid() explicitly. If you see this error on a new handler you've written, you've reproduced the same bug pattern — set the Id on each child before saving.

Notifications not arriving in email

• Email provider not configured — see §11. Settings → Email Provider.
• Enabled = false in email settings — flip it on.
• User has no email address — user creation requires a non-empty Email field; verify.
• Notification preferences toggled off — at /preferences, the user has opted out of that template + channel.
• Worker not running — check API console for NotificationDeliveryWorker startup logs. The worker is a hosted background service; if the API is up, it should be running.
• Looking in the queue — the NotificationDeliveries table stores every queued email. Filter by Status to see what's stuck (Failed rows have an ErrorMessage).

Where to find more

Going to production

This guide gets you to a running dev environment. For production deployment, additional steps:

1. Real secrets: generate a fresh JWT signing key, never use the default. Use environment variables / a secret store.
2. Real SMTP: configure email at /settings/email. Test with Send test email.
3. Real users: create your real accounts at /users; assign roles; deactivate demo users.
4. Change the admin password: at /profile.
5. HTTPS: terminate TLS at a reverse proxy (nginx, IIS, App Service) — the .NET host runs HTTP behind it.
6. Regular backups: SQL Server full + log backups; the AppData/Documents folder; the ASP.NET Core data-protection key ring (else the encrypted SMTP password becomes unrecoverable on restore).
7. Retention jobs: RequestLogs (90 days), Notifications (180 days after read), LoginAudits (per security policy). Operator-driven — no built-in cleaner.

See docs/06-operations for the operations-focused detail and a Dockerfile template.