Skip to content

Payroll Engine Backend

The Payroll Engine Backend is the central REST API server. It provides the full payroll data model via HTTP and manages persistence in SQL Server.

Overview

Property Value
Runtime .NET 10
Framework ASP.NET Core
Database SQL Server 2019+ · MySQL 8.4 LTS (preview)
API REST / OpenAPI 3.0
Authentication API key

Running

The recommended way to run the backend is via Docker Compose — see Container Setup for the full stack setup.

SQL Server: 

docker run -d \
  -e PayrollDatabaseConnection="Server=.;Database=PayrollEngine;Integrated Security=True;" \
  -p 5001:8080 \
  ghcr.io/payroll-engine/payrollengine.backend:latest

MySQL 8.4 LTS (preview): 

docker run -d \
  -e PayrollDatabaseConnection="Server=host.docker.internal;Port=3306;Database=PayrollEngine;User=root;Password=...;CharSet=utf8mb4;" \
  -e PayrollServerConfiguration__DbProvider=MySql \
  -p 5001:8080 \
  ghcr.io/payroll-engine/payrollengine.backend:latest

Pre-release images do not carry the :latest tag — use an explicit version tag instead.

Local

Prerequisites: .NET 10 Runtime, SQL Server 2019+

Download the latest release from GitHub Releases and configure appsettings.json:

{
  "PayrollDatabaseConnection": "Server=.;Database=PayrollEngine;Integrated Security=True;"
}

Start the backend:

dotnet PayrollEngine.Backend.dll

The backend verifies the database schema version on startup and refuses to start if a migration is required. Run ModelUpdate.sql against your database first, or use the Docker stack which handles migrations automatically.

Configuration

Database Connection

The connection string is read from PayrollDatabaseConnection in appsettings.json or via environment variable:

PayrollDatabaseConnection=Server=.;Database=PayrollEngine;Integrated Security=True;

API Key

Set a static API key for inbound authentication in apisettings.json (excluded from source control):

{
  "ApiKey": "your-api-key"
}

Clients pass the key in the X-Api-Key request header. If no API key is configured, the backend runs without authentication.

HTTPS / Insecure SSL

In local development with self-signed certificates, clients must set AllowInsecureSsl=true. In production, configure a valid certificate via standard ASP.NET Core HTTPS options.

Swagger UI

The Swagger UI is available at /swagger when the backend is running:

http://localhost:5001/swagger

The machine-readable OpenAPI specification is served at /swagger/v1/swagger.json and is the source of the REST API Reference.

Service Endpoints

Service Default URL
REST API http://localhost:5001
Swagger UI http://localhost:5001/swagger
Health check http://localhost:5001/health

See Also