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, MySQL, or PostgreSQL.

Overview

Property Value
Runtime .NET 10
Framework ASP.NET Core
Database SQL Server 2019+ · MySQL 8.4 LTS (preview) · PostgreSQL 14+
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=host.docker.internal;Database=PayrollEngine;User Id=sa;Password=...;TrustServerCertificate=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

PostgreSQL 14+: 

docker run -d \
  -e PayrollDatabaseConnection="Host=host.docker.internal;Port=5432;Database=PayrollEngine;Username=payroll;Password=...;" \
  -e PayrollServerConfiguration__DbProvider=Postgres \
  -p 5001:8080 \
  ghcr.io/payroll-engine/payrollengine.backend:latest

The image contains no database and no connection string — the database must exist with the Payroll Engine schema, and the connection string must be passed as shown above.

Stable releases publish latest on GHCR together with the version tag (for example 1.1.0). Pin a specific tag when you need a fixed build.

Local

Prerequisites: .NET 10 Runtime, SQL Server 2019+

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

{
  "ConnectionStrings": {
    "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 the schema is older than the minimum supported version. 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 the environment variable PayrollDatabaseConnection or from ConnectionStrings:PayrollDatabaseConnection in appsettings.json (container: ConnectionStrings__PayrollDatabaseConnection):

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