Installation — Prerequisites¶

What must be in place before the NKO ERP will build and run. This section covers a fresh installation from the source repository; for deploying a build to a server see Deployment.

Read this before you start

Two things in the repository will stop a fresh installation, and neither is obvious:

There is no way to create the first user. No seed data, no SQL script, no self-registration. A freshly migrated database has an empty ApplicationUsers table and every screen behind a permission check. See First Run — R5-1.
PDF export will not work. wwwroot/Rotativa/ and the wkhtmltopdf binaries it needs are not in the repository — R5-3.

Software¶

Requirement	Version	Notes
.NET SDK	6.0	All five projects target `net6.0`. Note that .NET 6 left support in November 2024 — see R1-7 in Recommendations.
SQL Server	2016 or later	Any edition, including Express for a development box
Windows	—	`System.Drawing.Common` 6.0.0 is Windows-only from .NET 6 onward, so the application is effectively Windows-bound
wkhtmltopdf	matching Rotativa 1.2.0	Required for every PDF export; not supplied in the repository
Visual Studio 2022 or `dotnet` CLI	—	Runtime view compilation is enabled, so views can be edited without a rebuild

Databases¶

Three databases are needed. They may live on the same SQL Server instance.

Database	Connection string	Created by
`NKO_DB`	`HrConnection`	EF migrations (18)
`NKO_DB_Warehouse`	`WareConnection`	EF migrations (5)
Hangfire store	`HangfireConnection`	Hangfire itself — `PrepareSchemaIfNecessary = true` creates the schema, but the database must already exist

See Database Setup.

External accounts¶

Service	Needed for	Where it is configured
AWS S3	All document storage — attachments, contracts, e-signatures. The application will start without it but every upload and download fails.	`appsettings.json` → `StorageConfigs`
SMTP mailbox	Approval notifications, security alerts, birthday mail	Hard-coded in `SiteSettings.cs` — see the warning below
data.fixer.io	Not needed. The client exists but is never called (R7-17). Its absence has a consequence, though: the global exchange rate has no update path in the application, so it must be inserted into the `ExchangeRates` table directly — purchase requests use it (R7-1)	—

Two settings files, and secrets in the wrong one — R1-9

Configuration is split in a way that is easy to get wrong:

appsettings.json holds the connection strings, StorageConfigs, SysUrl, JwtConfig:Secret and the scheduled-job settings. It is not committed; appsettings.example.json shows the shape.
NKO.Lib/NKO.Shared/Helpers/SiteSettings.cs holds the rest — site name, all URLs, the HR mailbox, the template path, and both mailbox passwords — as public static string literals compiled into the assembly. Changing any of them requires a rebuild and redeploy, and the passwords are in source control.

When installing a new environment you must edit both.

Configuration file¶

Copy appsettings.example.json to appsettings.json and fill in:

{
  "ConnectionStrings": {
    "HrConnection":       "Server=…;Database=NKO_DB;…",
    "WareConnection":     "Server=…;Database=NKO_DB_Warehouse;…",
    "HangfireConnection": "Server=…;Database=NKO_Hangfire;…"
  },
  "StorageConfigs": {
    "region":       "…",
    "clientId":     "…",
    "clientSecret": "…"
  },
  "SysUrl": "https://your-host/",
  "EPPlus": { "ExcelPackage": { "LicenseContext": "NonCommercial" } },
  "ScheduledJobsSettings": {
    "BirthdayGreetingsIsActive": true,
    "BirthdayGreetingsCronExpression": "…"
  }
}

JwtConfig:Secret is not needed. Startup reads it only inside the AddJwtBearer(...) options callback, which ASP.NET Core runs only if the JWT scheme is ever used — and it never is, because AddIdentity makes the Identity cookie the default scheme (R6-4). Neither appsettings.example.json nor a working configuration defines it. See Deployment — Configuration for every key the application reads.

Add the NKODestruction storage entry

appsettings.example.json lists 18 StorageConfigs:Systems entries, but the code uses 19. Without a NKODestruction entry, every attachment upload on an asset-disposal request throws — see R4-1 and Deployment — Configuration.

Check the EPPlus licence

LicenseContext is set to NonCommercial. EPPlus has been dual-licensed since version 5 — confirm the terms cover an ERP running an organisation's payroll and procurement (R1-8).

Values that require a code change¶

These are compiled in, so a new environment means editing source and rebuilding:

Setting	File
Site name, `SystemURL`, `SiteURL`, `JobCenterURL`, `JobCenterRFQURL`, `SiteVacancyURL`	`NKO.Shared/Helpers/SiteSettings.cs`
`HREmail`, `SystemEmail`, `AutoReplyEmail` and both passwords	`NKO.Shared/Helpers/SiteSettings.cs`
`TemplatePath` — where the e-signature PDF template lives	`NKO.Shared/Helpers/SiteSettings.cs`
SMTP host and port	`NKO.Shared/Helpers/EmailManager.cs`
`data.fixer.io` access key (unused)	`NKO.Main/BAL/BExchangeRate.cs`

Restore and build¶

cd NKO.Main
dotnet restore
dotnet build

dotnet restore pulls about 44 packages including the AWS SDK, Hangfire, Quartz, EPPlus, Rotativa and — unnecessarily — Refit, Twilio and MailKit, none of which the code uses (R1-4).

wkhtmltopdf¶

Startup.Configure runs RotativaConfiguration.Setup(env.WebRootPath, "Rotativa"), which expects the wkhtmltopdf executable under NKO.Main/NKO.Main/wwwroot/Rotativa/. That folder is not in the repository. Obtain the binaries matching Rotativa.AspNetCore 1.2.0, create the folder and place them there before expecting any PDF to render (R5-3).

Next¶

Database Setup — creating and migrating both contexts
First Run — starting the application and getting the first account in