Configuring Vinyl on Startup¶

Overview¶

Configuration is supplied by the environment and applied on startup.

Vinyl configuration is based on the ASP.NET Core configuration system.

Sources¶

Vinyl supports multiple configuration sources, including:

• appsettings.json
• Environment Variables

appsettings.json¶

The appsettings.json file is a JSON file located in the Vinyl installation directory. Vinyl does not ship with an appsettings.json file: administrators need to create an appsettings.json.

The samples directory contains many example appsettings.json files. Administrators may start with one of these.

cd C:\inetpub\wwwroot\Vinyl\
cp .\samples\appsettings.connectioninfo.json .\appsettings.json

Or, to start from an empty file:

cd C:\inetpub\wwwroot\Vinyl\
"{}" | Out-File appsettings.json

Environment Variables¶

Configuration can also be supplied via system environment variables. A double-underscore is used for hierarchical keys.

The following environment variables:

ConnectionInfo__DatabaseType=SQLServer
ConnectionInfo__HostName=localhost
ConnectionInfo__DatabaseName=Vinyl
ConnectionInfo__UserName=Vinyl
ConnectionInfo__Password=password

Map to the equivalent JSON:

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

Settings¶

ConnectionInfo¶

The ConnectionInfo section supplies the Vinyl database connection information.

ConnectionInfo Keys¶

DatabaseType Values¶

ConnectionInfo Example¶

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

Tls¶

The Tls section configures TLS protocol support.

Tls Keys¶

SecurityProtocolType Values¶

Security protocol types are derived from the SecurityProtocolType enumeration.

Tls Example¶

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

ReverseProxy¶

The ReverseProxy section configures reverse proxy support.

ReverseProxy Keys¶

ReverseProxy Example¶

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

UrlRewrite¶

The UrlRewrite section configures URL rewriting support.

UrlRewrite Keys¶

UrlRewrite Example¶

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

DataEncryption¶

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

DataEncryption Keys¶

KeyEncryption Values¶

KeyStorage Values¶

DataEncryption Example¶

{
  "DataEncryption": {
    "KeyStorage": "Database",
    "KeyEncryption": "Kms",
    "KmsKeyId": "arn:aws:kms:us-east-1:1234567890:key/1234abcd-12ab-34cd-56ef-1234567890ab"
  }
}

SharedState¶

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

SharedState Keys¶

SharedStateProviderType Values¶

SharedState Example¶

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

Site¶

The Site section configures the Vinyl web site address and known aliases.

Site Keys¶

SiteAlias Keys¶

Site Example¶

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

Security¶

The Security section configures Vinyl user accounts and security providers.

Security Keys¶

User Keys¶

SecurityProvider Keys¶

Security Example¶

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

License¶

The License section supplies the Vinyl license.

License Keys¶

License Example¶

{
  "License": {
    "LicenseKey": "Tm93IGlzIHRoZSB3aW50ZXIgb2Ygb3VyIGRpc2NvbnRlbnQ="
  }
}

SignalR¶

The SignalR section configures client-server communications.

SignalR Keys¶

HttpTransportType Values¶

HTTP transport types are derived from the HttpTransportType enumeration.

SignalR Example¶

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

Scripting¶

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

Scripting Keys¶

Scripting Example¶

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

ASP.NET Options¶

Configuration is based on the ASP.NET Core configuration system. The same configuration sources can be used to configure .NET.

Kestrel¶

The Kestrel section configures the Kestrel web server. Consult the Kestrel documentation for a list of supported options.

Kestrel Example¶

{
  "Kestrel": {
    "Limits": {
      "MaxRequestBodySize": 100000000
    }
  }
}

Transitioning from connection.xml to System Environment Variables¶

If you are upgrading Vinyl from a version earlier than Vinyl 3.0, you may optionally transition from using connection.xml to system environment variables to better obscure the Vinyl database connection string.

Vinyl will resolve database settings in the following order:

1. System Environment Variables
2. appsettings.json
3. Connection.xml

The basic steps to follow for transitioning from connection.xml to environment variables are:

1. Create system environment variables with the exact names. A web server restart may be required for the environment variables to persist.

   ConnectionInfo__DatabaseType
   ConnectionInfo__HostName
   ConnectionInfo__DatabaseName
   ConnectionInfo__UserName
   ConnectionInfo__Password
   

2. Remove the connection.xml file from Vinyl root

3. Recycle the Vinyl app pool