Training:Set up MDriven Turnkey on premise

Set up MDriven Turnkey on premise

This page was created by Stephanie on 2023-06-15. Last edited by Wikiadmin on 2026-07-29.

You can run MDriven Turnkey and MDrivenServer entirely on your own Microsoft IIS server; this guide is for administrators who need an on-premise Turnkey site rather than an Azure-hosted site.

What you will install

An on-premise installation contains two IIS applications:

Application	Purpose	Example URL
MDriven Turnkey	The application users open.	`https://localhost/MyMDrivenTurnkeyApp1/`
`__MDrivenServer`	The MDriven Server used by Turnkey and MDriven Designer to store, upload, and deploy models.	`https://localhost/MyMDrivenTurnkeyApp1/__MDrivenServer/`

The MDriven Server application name must be __MDrivenServer, with two leading underscore characters. Turnkey uses this location when it connects to the server.

Before you begin

Prepare the following:

A Windows server with IIS installed.
An IIS application for the Turnkey site and a nested IIS application named __MDrivenServer.
The MDriven Turnkey and MDriven Server application packages, available from MDriven downloads. You need both packages.
HTTPS configured in IIS. The communication between Turnkey and MDriven Server requires HTTPS. For development, you can use a self-signed certificate; use a certificate trusted by your users for a production site.
Permission to change IIS bindings, application-pool settings, and folder permissions.

If IIS does not offer the application-package import actions, install the IIS Web Deploy extension. The package import process is also useful when you later update either application.

Create the IIS application structure

In IIS Manager, create an application for the Turnkey site. For example, create MyMDrivenTurnkeyApp1.
Choose an existing physical folder or create the folder that will hold the Turnkey application files.
Under the Turnkey application, create a second IIS application named __MDrivenServer.
Set the physical path of the nested application to the folder that will hold the MDriven Server files.

Your IIS structure should look like this:

MyMDrivenTurnkeyApp1
└── __MDrivenServer

Do not install both packages into the same physical folder. Turnkey belongs in the parent application; MDriven Server belongs in the nested __MDrivenServer application.

Import the application packages

Import the MDriven Turnkey application package into the parent Turnkey IIS application.
Import the MDriven Server application package into the __MDrivenServer IIS application.
Confirm that each package was imported into its intended application before continuing.

For example, with the application structure above, import Turnkey into MyMDrivenTurnkeyApp1 and import MDriven Server into MyMDrivenTurnkeyApp1/__MDrivenServer.

Configure HTTPS

Configure an HTTPS binding for the IIS site that hosts the applications. Select a certificate that IIS can use for that binding.

For a local development machine, create and bind a self-signed certificate. For a site used by other people, bind a certificate that their browsers trust. Do not continue with HTTP-only access: Turnkey-to-server communication requires HTTPS.

After you create the binding, verify that the MDriven Server URL opens over HTTPS:

https://localhost/MyMDrivenTurnkeyApp1/__MDrivenServer/

Replace localhost and MyMDrivenTurnkeyApp1 with your server name and IIS application path.

Give MDriven Server access to its log folder

MDriven Server writes logs under __MDrivenServer/logs. Give the IIS application-pool identity read and write access to this folder.

Locate the physical __MDrivenServer/logs folder in File Explorer.
Open the folder's security settings.
Add IIS AppPool\NameOfTheAppPool, replacing NameOfTheAppPool with the application pool used by the MDriven Server application.
Grant read and write access.

Without this access, diagnostics and runtime behavior can be impaired.

Initialize and secure MDriven Server

Initialize the server database

Browse to the MDriven Server URL over HTTPS.
On the first visit, MDriven Server can report that its expected database is not present. This is the initialization response: the server creates the database and applies its setup.
Select Index to return to the default page.
Register a user and record the password. This user can be used to administer MDriven Server and to let Turnkey connect to it.
Sign in with the user you created.

Configure users and access requirements

In the MDriven Server administration area, open User admin.
Create or identify the account that the Turnkey site will use to access MDriven Server.
Assign the SuperAdmin role to each user who must administer MDriven Server.
Enable Admin require Identification.
Enable Services require identification.
Enable Turn off registration.

Turning off registration prevents new users from registering through the server. Record the credentials for every administrator before enabling it. If you lose all administrator credentials while registration is disabled, you can lock yourself out.

Recover access if registration was disabled

If registration has been disabled and no usable administrator account remains:

Open the MDriven Server administration database with SQL Server Compact tools.
Locate admin_GlobalSettings.
Set the TurnOffRegistration column to 0 (false).
Register a new user, then restore the intended access settings.

The database file is located at:

__MDrivenServer\App_Data\DatabaseCompact.sdf

Connect Turnkey to MDriven Server

When you first browse to the parent Turnkey application, for example https://localhost/MyMDrivenTurnkeyApp1, it cannot connect until it has credentials for MDriven Server.

Turnkey reads those credentials from App_Data\TurnkeySettings.xml.

In the Turnkey application's App_Data folder, find TurnkeySettings - NotInEffect.xml.
Copy the file.
Name the copy TurnkeySettings.xml.
Edit TurnkeySettings.xml and enter the MDriven Server user name and password you created earlier.
Restart the Turnkey application pool so that Turnkey reads the new file.
Browse to the Turnkey application again and verify that it starts.

On a locally installed site, you manage this file yourself. The LicenseAndTicket website does not manage local installation settings.

Connect MDriven Designer

You must enter the on-premise MDriven Server address in MDriven Designer rather than using the initial login page.

In MDriven Designer, skip the first login page and open the next connection page.
Enter the user name and password for an account that can access your MDriven Server.
Set the slot to A0.
Select Automated Deploy if you want each model upload to deploy automatically.
Enter the MDriven Server address, for example:

https://localhost/MyMDrivenTurnkeyApp1/__MDrivenServer

With Automated Deploy enabled, uploading a model from MDriven Designer deploys that model to the server automatically. Your Turnkey application must contain an Index ViewModel for the application to open correctly.

Update the installed applications

To update MDriven Turnkey or MDriven Server binaries, import a newer application package into the corresponding existing IIS application.

When importing an update, choose Append files. Do not choose an option that deletes existing files: deleting files can remove your local settings, database, and deployed models.

After an update, verify both endpoints:

Browse to https://localhost/MyMDrivenTurnkeyApp1/__MDrivenServer/ and sign in to MDriven Server.
Browse to https://localhost/MyMDrivenTurnkeyApp1/ and verify that Turnkey starts.
Open MDriven Designer, connect to the on-premise server, and confirm that you can upload and deploy a model.

Troubleshooting

Symptom	Check
MDriven Server or Turnkey reports communication errors	Confirm that the IIS site has a working HTTPS binding and that you are using an `https://` URL.
Turnkey does not start after installation	Confirm that `App_Data\TurnkeySettings.xml` exists, contains the MDriven Server credentials, and that the Turnkey application pool was restarted after editing it.
Turnkey cannot reach MDriven Server	Confirm that MDriven Server is installed as the nested IIS application named exactly `__MDrivenServer` and that its HTTPS URL opens in a browser.
Logging or server runtime behavior is unreliable	Confirm that the MDriven Server application-pool identity has read/write access to `__MDrivenServer/logs`.
No administrator can sign in and registration is disabled	Set `admin_GlobalSettings.TurnOffRegistration` to `0` in `__MDrivenServer\App_Data\DatabaseCompact.sdf`, register a new user, and reconfigure access.

Contents