Configuration Reference

All configuration is managed via appsettings.json and can be overridden with environment variables using the __ (double-underscore) convention.

Connection Strings

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=HeadlessEcommerce;Username=postgres;Password=postgres123"
  }
}

Key	Description
DefaultConnection	PostgreSQL connection string

JWT Authentication

{
  "Jwt": {
    "SecretKey": "YourSuperSecretKeyHere12345678901234567890",
    "Issuer": "HeadlessEcommerceApi",
    "Audience": "HeadlessEcommerceClient",
    "ExpirationMinutes": 60
  }
}

Key	Description	Default
SecretKey	HMAC signing key (min 32 chars)	—
Issuer	Token issuer claim	HeadlessEcommerceApi
Audience	Token audience claim	HeadlessEcommerceClient
ExpirationMinutes	Access token lifetime	60

danger

Use a strong, random SecretKey in production. Never reuse the development key.

RabbitMQ

{
  "RabbitMQ": {
    "Host": "localhost",
    "Port": 5672,
    "VirtualHost": "/",
    "Username": "guest",
    "Password": "guest",
    "QueuePrefix": "quark",
    "EnableOutbox": true,
    "OutboxDeliveryIntervalSeconds": 5,
    "MaxRetryCount": 5,
    "RetryIntervalSeconds": 5
  }
}

Key	Description	Default
Host	RabbitMQ server hostname	localhost
Port	AMQP port	5672
VirtualHost	RabbitMQ virtual host	/
QueuePrefix	Prefix for queue names	quark
EnableOutbox	Enable transactional outbox	true
OutboxDeliveryIntervalSeconds	Polling interval for outbox publisher	5
MaxRetryCount	Max delivery attempts before marking failed	5

The outbox publisher writes events to the database in the same transaction as business operations, then a background service polls and publishes them to RabbitMQ via a topic exchange (quark.events).

Storage

{
  "Storage": {
    "Provider": "Local",
    "BaseUrl": "http://localhost:8080/media",
    "MaxFileSizeMB": 50,
    "AllowedExtensions": [".jpg", ".png", ".webp", "..."],
    "Local": {
      "RootPath": "wwwroot/media",
      "RequestPath": "/media"
    },
    "NetworkShare": {
      "RootPath": "//nas01/commerce-media",
      "BaseUrl": "https://cdn.example.com"
    },
    "S3": {
      "Bucket": "my-commerce-assets",
      "Region": "eu-central-1",
      "BaseUrl": "https://cdn.example.com",
      "UsePresignedUrls": false
    }
  }
}

Key	Description	Default
Provider	Storage backend: Local, NetworkShare, or S3	Local
BaseUrl	Public base URL for media files	http://localhost:8080/media
MaxFileSizeMB	Maximum upload file size	50

tip

In production, set Storage.BaseUrl to your public domain (e.g., https://quarkapi.yourdomain.com/media). This URL is stored in the database and used to construct media URLs returned by the API.

Rate Limiting

{
  "RateLimiting": {
    "Enabled": true,
    "Fixed": {
      "PermitLimit": 100,
      "WindowSeconds": 60,
      "QueueLimit": 10
    },
    "Search": {
      "PermitLimit": 60,
      "WindowSeconds": 60,
      "QueueLimit": 5
    },
    "Sliding": {
      "PermitLimit": 20,
      "WindowSeconds": 10,
      "SegmentsPerWindow": 2,
      "QueueLimit": 5
    }
  }
}

Three rate limit policies are applied:

• Fixed — global rate limit for all endpoints
• Search — stricter limit for search endpoints
• Sliding — burst protection with sliding window

Licensing

{
  "Licensing": {
    "PublicKeyBase64": "base64-encoded-rsa-4096-public-key",
    "LicenseFilePath": "/path/to/license.lic",
    "LicenseFileBase64": "base64-encoded-license-file",
    "PhoneHomeUrl": "https://license-server.yourdomain.com/api/phone-home"
  }
}

Key	Description
PublicKeyBase64	RSA-4096 public key for signature verification
LicenseFilePath	Path to license file on disk (local dev)
LicenseFileBase64	Base64-encoded license file (production, via env var)
PhoneHomeUrl	Optional URL for periodic license validation callbacks

For production, prefer environment variables:

Licensing__PublicKeyBase64=...
Licensing__LicenseFileBase64=...

Stripe

{
  "Stripe": {
    "SecretKey": "sk_test_..."
  }
}

Caching

{
  "Caching": {
    "Enabled": true
  }
}

When enabled, storefront endpoints use response caching (300s default) with Vary on store/language/currency headers.

Logging

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Standard ASP.NET Core logging configuration. Adjust log levels per namespace as needed.

Environment Variable Mapping

The __ convention maps to JSON nesting:

Environment Variable	JSON Path
ConnectionStrings__DefaultConnection	ConnectionStrings.DefaultConnection
Jwt__SecretKey	Jwt.SecretKey
RabbitMQ__Host	RabbitMQ.Host
Storage__BaseUrl	Storage.BaseUrl
Licensing__PublicKeyBase64	Licensing.PublicKeyBase64