Skip to Content

Startup configuration

Introduction

This page describes Vinyl's startup configuration parameters and methods. Each section is the top-level schema for the JSON form (appsettings.json) configuration method.

When Vinyl starts, it gets its configuration values from any of the following sources, in order of precedence:

  1. System environment variables.
  2. An ASP.NET Core appsettings.json JSON file.
  3. (Vinyl 3.0 and earlier) A connection.xml XML file with a <ConnectionInfo> element.

System environment variables are the JSON schemas, sub-schemas (if any), and keys separated by two underscore characters. There is no default appsettings.json file. You can create one in the installation directory using the samples in C:\inetpub\wwwroot\Vinyl\ (Windows) or the samples sub-directory (Linux), many of which are reproduced on this page.

As an example, the following configuration methods provide equivalent values:

Environment variables
ConnectionInfo__DatabaseType=SQLServer
ConnectionInfo__HostName=localhost
ConnectionInfo__DatabaseName=Vinyl
ConnectionInfo__UserName=vinyl
ConnectionInfo__Password=P@5$w0rD
appsettings.json file
{
  "ConnectionInfo": {
    "DatabaseType": "SQLServer",
    "HostName": "localhost",
    "DatabaseName": "Vinyl",
    "UserName": "vinyl",
    "Password": "P@5$w0rD"
  }
}
connection.xml file
<ConnectionInfo DatabaseType="MySQL" HostName="localhost" DatabaseName="Vinyl" UserName="vinyl" Password="P@5$w0rD"/>

BackgroundService

Schema Key Value Type Description
BackgroundService DisableScheduler Boolean Set to true to disable the background services scheduler.

Examples

JSON
{
  "BackgroundService": {
    "DisableScheduler": true
  }
}
Environment variable
BackgroundService__DisableScheduler=true

ConnectionInfo

Schema Key Value Type Description
ConnectionInfo DatabaseType String Database type: SQLServer, MySQL, PostgreSql
HostName String Database server host name or IP address.
Port Integer Database server port number.
InstanceName String Database server instance name.
TenantName String For internal use.
DatabaseName String Vinyl database name.
UserName String Vinyl database username.
Password String Vinyl database password.
ConnectionTimeout Integer Database connection timeout (seconds).
CommandTimeout Integer Database command timeout (seconds).
MaxPoolSize Integer Maximum number of Database connections in the pool.
Advanced Object array Additional connection string key/value pairs.

Examples

{
  "ConnectionInfo": {
    "DatabaseType": "SQLServer",
    "HostName": "localhost",
    "DatabaseName": "Vinyl",
    "UserName": "Vinyl",
    "Password": "password"
  }
}

DataEncryption

The DataEncryption section configures Data Encryption Key (DEK) storage and encryption.

Schema Key Value Type Description
DataEncryption Certificate String Base64-encoded, PKCS#12 (PFX) X.509 certificate.
CertificatePassword String X.509 certificate password.
CertificateThumbprint String X.509 certificate thumbprint.
Directory String File system directory path.
Import String Storage and encryption policies for importing DEKs.
KeyEncryption String Data encryption strategy:
  • Certificate: X.509 certificate encryption policy.
  • Kms: AWS KMS key encryption policy.
  • None: No key encryption policy. Keys are stored in plain text.
  • Null: Passthrough key encryption policy. Keys are stored in plain text.
KeyStorage String Data encryption key storage location:
  • Database: Vinyl database.
  • FileSystem: File system.
  • ParameterStore: AWS System Manager Parameter Store.
  • S3: S3 bucket.
KmsKeyId String AWS KMS key ARN.
ParameterNamePrefix String AWS System Manager Parameter Store parameter name prefix.
S3BucketEndpoint String S3 bucket endpoint.
S3KeyPrefix String S3 key prefix.

Examples

{
  "DataEncryption": {
    "KeyEncryption": "Certificate",
    "CertificateThumbprint": "a909502dd82ae41433e6f83886b00d4277a32a7b",
    "Certificate": "{base64-pfx-data}",
    "CertificatePassword": "your-certificate-password"
  }
}

{
  "DataEncryption": {
    "KeyEncryption": "Kms",
    "KmsKeyId": "{kms-key-arn}"
  }
}

{
  "DataEncryption": {
    "KeyEncryption": "None"
  }
}

{
  "DataEncryption": {
    "KeyEncryption": "Null"
  }
}

{
  "DataEncryption": {
    "KeyStorage": "Database"
  }
}

{
  "DataEncryption": {
    "KeyStorage": "FileSystem",
    "Directory": "C:\\Path\\To\\Keys"
  }
}

{
  "DataEncryption": {
    "KeyStorage": "ParameterStore",
    "ParameterNamePrefix": "/production"
  }
}

{
  "DataEncryption": {
    "KeyStorage": "S3",
    "S3BucketEndpoint": "https://{bucket}.s3{-aws-region}.amazonaws.com",
    "S3KeyPrefix": "production"
  }
}

Kestrel

The Kestrel section configures the Kestrel web server.

Schema Key Value Type Description
Kestrel Limits MaxRequestBodySize See the Kestrel documentation for a list of supported options.

License

The License section specifies the Vinyl license key.

Schema Key Value Type Description
License LicenseKey String A base64-encoded version of your vinyl.lic file.

Examples

{
  "License": {
    "LicenseKey": "TWF1cmlzIGFjIGZlbGlzIHZlbCB2ZWxpdCB0cmlzdGlxdWUgaW1wZXJkaWV0LiAgTnVsbGFtIGV1IGFudGUgdmVsIGVzdCBjb252YWxsaXMgZGlnbmlzc2ltLiAgRnVzY2Ugc3VzY2lwaXQsIHdpc2kgbmVjIGZhY2lsaXNpcyBmYWNpbGlzaXMsIGVzdCBkdWkgZmVybWVudHVtIGxlbywgcXVpcyB0ZW1wb3IgbGlndWxhIGVyYXQgcXVpcyBvZGlvLiAgTnVuYyBwb3J0YSB2dWxwdXRhdGUgdGVsbHVzLiAgTnVuYyBydXRydW0gdHVycGlzIHNlZCBwZWRlLiAgU2VkIGJpYmVuZHVtLiAgQWxpcXVhbSBwb3N1ZXJlLiAgTnVuYyBhbGlxdWV0LCBhdWd1ZSBuZWMgYWRpcGlzY2luZyBpbnRlcmR1bSwgbGFjdXMgdGVsbHVzIG1hbGVzdWFkYSBtYXNzYSwgcXVpcyB2YXJpdXMgbWkgcHVydXMgbm9uIG9kaW8uICBQZWxsZW50ZXNxdWUgY29uZGltZW50dW0sIG1hZ25hIHV0IHN1c2NpcGl0IGhlbmRyZXJpdCwgaXBzdW0gYXVndWUgb3JuYXJlIG51bGxhLCBub24gbHVjdHVzIGRpYW0gbmVxdWUgc2l0IGFtZXQgdXJuYS4gIEN1cmFiaXR1ciB2dWxwdXRhdGUgdmVzdGlidWx1bSBsb3JlbS4gIEZ1c2NlIHNhZ2l0dGlzLCBsaWJlcm8gbm9uIG1vbGVzdGllIG1vbGxpcywgbWFnbmEgb3JjaSB1bHRyaWNlcyBkb2xvciwgYXQgdnVscHV0YXRlIG5lcXVlIG51bGxhIGxhY2luaWEgZXJvcy4gIFNlZCBpZCBsaWd1bGEgcXVpcyBlc3QgY29udmFsbGlzIHRlbXBvci4gIEN1cmFiaXR1ciBsYWNpbmlhIHB1bHZpbmFyIG5pYmguICBOYW0gYSBzYXBpZW4uCg=="
  }
}

PostgreSQL

Schema Key Value Type Description
PostgreSQL Logging
OpenTelemetry

ReverseProxy

The ReverseProxy section configures a reverse proxy.

Schema Key Value Type Description
ReverseProxy ForwardedClientIpHeader String HTTP header that forwards the original client IP address.
ForwardedSchemeHeader String HTTP header that forwards the original scheme.
ForwardedHostHeader String HTTP header that forwards the original host and optional port. Since Vinyl 3.3.34291.
ForwardedPortHeader String HTTP header that forwards the original port.

Examples

{
  "ReverseProxy": {
    "ForwardedClientIpHeader": "X-Forwarded-For",
    "ForwardedSchemeHeader": "X-Forwarded-Proto",
    "ForwardedHostHeader": "X-Forwarded-Host"
  }
}

{
  "ReverseProxy": {
    "ForwardedClientIpHeader": "X-Forwarded-For",
    "ForwardedSchemeHeader": "X-Forwarded-Proto",
    "ForwardedPortHeader": "X-Forwarded-Port"
  }
}

Security

The Security section configures Vinyl user accounts and security providers.

Schema Key Value Type Description
Security Administrator Schema Admin account options.
InvitationUrl String For internal use.
LocalAuthentication Schema Local user security provider options.
Provider String Base64-encoded security provider configuration.
Providers String array base64-encoded security provider configuration.
AuthenticationExpiry Integer Authentication token expiration, in minutes. Since Vinyl 3.3.34291.
Schema Key Value Type Description
Administrator AllowLocalAuthentication Boolean Enables local user authentication.
ChangePasswordOnLogin Boolean Forces user to change password on login.
DefaultPassword String Default password. Applied once on installation.
Password String Password. Applied each time the system starts.
Schema Key Value Type Description
LocalAuthentication Enabled Boolean Enables the security provider.
ShowOnLoginForm Boolean Determines if the user authentication provider appears on the login form.

Examples

{
  "Security": {
    "Administrator": {
      "Password": "s3cr3t",
      "ChangePasswordOnLogin": false
    },
    "LocalAuthentication": {
      "ShowOnLoginForm": false
    },
    "Provider": "Tm90aGluZyBjYW4gY29tZSBvZiBub3RoaW5nLCBzcGVhayBhZ2Fpbi4="
  }
}

Scripting

The Scripting section configures Vinyl's C# scripting SDK.

Schema Key Value Type Description
Scripting Enabled Boolean Enables C# scripting.

Examples

{
  "Scripting": {
    "Enabled": false
  }
}

SharedState

The SharedState section configures the shared-state service which supports multi-server deployments.

Schema Key Value Type Description
SharedState Provider String Shared state provider:
  • InProcess: State is stored in-process for single-server deployments.
  • Redis: State is stored in Redis for multi-server deployments.
RedisConnectionString String Redis connection string.
RedisPrefix String Redis key prefix.

Example

{
  "SharedState": {
    "Provider": "Redis",
    "RedisConnectionString": "localhost:6379"
  }
}

SignalR

The SignalR section configures client-server communications.

Schema Key Value Type Description
SignalR LongPollingTimeout String Long polling timeout, specified using a TimeSpan format. Example: 00:00:30.
Transports String Comma-delimited list of HTTP transport types:
  • LongPolling: Long-polling.
  • None: No transports. NOT SUPPORTED.
  • ServerSentEvents: Server-sent events.
  • WebSockets: WebSockets
.

Examples

{
  "SignalR": {
    "Transports": "WebSockets,LongPolling",
    "LongPollingTimeout": "00:00:30"
  }
}

Site

The Site section configures the Vinyl website address and known aliases.

Schema Key Value Type Description
Site Url String Canonical web site URL.
Default Boolean Treat as the default web site.
Redirect Boolean Redirect clients to the site URL.
RedirectIfHeaderExists String HTTP header that indicates clients should be redirected.
AllowCrossOrigin Boolean Allow cross-origin requests.
Aliases String array Site aliases.

Examples

{
  "Site": {
    "Url": "https://example.com/Vinyl",
    "Default": true,
    "Redirect": true,
    "RedirectIfHeaderExists": "X-Forwarded-For",
    "Aliases": [
      {
        "Url": "https://vinyl.example.com"
      }
    ]
  }
}

Sku

Schema Key Value Type Description
Sku Sku String

Tls

The Tls section configures TLS protocol support.

Schema Key Value Type Description
Tls SecurityProtocol String Comma-delimited list of security protocols:
  • Ssl3: SSL 3.0
  • SystemDefault: System default protocol support.
  • Tls: TLS 1.0
  • Tls11: TLS 1.1
  • Tls12: TLS 1.2
  • Tls13: TLS 1.3

Examples

{
  "Tls": {
    "SecurityProtocol": "Tls,Tls11,Tls12"
  }
}

UrlRewrite

The UrlRewrite section configures URL rewriting support.

Schema Key Value Type Description
UrlRewrite OriginalUrlHeader String HTTP header that forwards the original URL.

Examples

{
  "UrlRewrite": {
    "OriginalUrlHeader": "X-Original-URL"
  }
}