HowTos:Install MDriven Server and Turnkey on Windows (.NET Core)

Install MDriven Server and Turnkey on Windows (.NET Core)

This guide installs the .NET Core builds of MDriven Server and MDriven Turnkey on Windows with IIS. It is the recommended way to run MDriven on Windows. If you use the .NET Framework build, see Install on Windows – .NET Framework instead.

Two ways to do it:

With the MDriven Installation Scripts – PowerShell scripts that create the IIS setup, install the zips, write the settings files and connect MDriven Server to its database. Recommended when you install more than once or keep several environments (Dev, Test, Production): MDriven Installation Scripts.
By hand in IIS Manager – the steps below, with details in Manual installation of the Core builds in IIS.

Both need the same preparation (step 1 and 2). Background on how the Core builds run: How MDriven Core runs.

1. Prepare the server

A supported version of Windows Server or Windows 10/11. See Microsoft's list of supported Windows versions for .NET 10.
IIS with these features (Server Manager → Add Roles and Features → Web Server (IIS), or Turn Windows features on or off on Windows 10/11):
- Common HTTP Features: Default Document, HTTP Errors, Static Content
- Health and Diagnostics: HTTP Logging (and Request Monitor, Tracing if you want them)
- Security: Request Filtering (and Windows Authentication if you use it)
- Application Development: WebSocket Protocol – required by both MDriven Server and MDriven Turnkey, see Turn on WebSockets in IIS
- Management Tools: IIS Management Console, and IIS Management Scripts and Tools if you use the MDriven Installation Scripts
- ASP.NET 4.x, ISAPI and WCF features are not needed for the Core builds.
The ASP.NET Core Hosting Bundle, from Microsoft's .NET download page (choose the current version, Hosting Bundle under ASP.NET Core Runtime for Windows). It installs the ASP.NET Core Module that lets IIS start the MDriven programs. Install IIS first. If you add IIS after the Hosting Bundle, run the Hosting Bundle installer again and choose Repair. Check afterwards that AspNetCoreModuleV2 is listed under Modules in IIS Manager.
A certificate for the address you will use, if you use https – see Certificates and HTTPS on IIS. MDriven Server calls itself, so it must be able to trust its own certificate.
The two downloads from the MDriven downloads page: MDriven Server and MDriven Turnkey, variant Windows .NET Core.

2. Choose the layout

Layout	Addresses	What Turnkey needs to find MDriven Server
MDriven Server below Turnkey (the default)	Turnkey: `https://myapp.example.com/` MDriven Server: `https://myapp.example.com/__MDrivenServer/`	Nothing – Turnkey looks for its server at its own address followed by `/__MDrivenServer`
Separate applications or sites	e.g. `https://server/MyApp/` and `https://server/MyAppServer/`	`App_Data/MDrivenServerOverride.xml` in Turnkey with the server's address and password – see MDrivenServerOverride

The default layout is the simplest: one site, with Turnkey in the root and MDriven Server as an application called __MDrivenServer (two underscores) below it.
Separate applications make sense when one server has several environments (Dev1, Test, …) or several Turnkey apps that share one MDriven Server, when the server and Turnkey are on different machines, or behind a load balancer. The MDriven Installation Scripts use this layout.
In both layouts, give each application its own application pool.

3. Install

With the MDriven Installation Scripts

Follow MDriven Installation Scripts: describe the environment in a settings file, preview, and run. The scripts do everything in step 3 and 4.

By hand

For each of the two applications (MDriven Server and MDriven Turnkey):

Create a folder and unzip the download into it, for example C:\inetpub\wwwroot\MyApp (Turnkey) and C:\inetpub\wwwroot\MyApp\__MDrivenServer (MDriven Server, default layout).
Create an application pool with .NET CLR version = No Managed Code. Recommended settings under Advanced Settings: Start Mode = AlwaysRunning, Disable Overlapped Recycle = True, and a fixed recycle time instead of the default 29-hour interval.
Create the site or application in IIS Manager, point it to the folder, and choose the application pool. For the default layout: the Turnkey folder is the site (or an application), and __MDrivenServer is an application below it.
Give the application pool user (IIS AppPool\<pool name>) write access to the application folder – see AppPool user.
Create App_Data\CommandLineOverride.xml with the application's address, exactly as it is reached in IIS:

<root>
  <arg>iis=https://myapp.example.com/__MDrivenServer</arg>
</root>

For Turnkey, use Turnkey's own address (for example https://myapp.example.com/). Example files are included in the zip as App_Data\CommandLineOverride - NotInEffect.xml.
Separate layout only: create App_Data\MDrivenServerOverride.xml in Turnkey with the server's address and the password of the server user a – see MDrivenServerOverride. An example is included in the Turnkey zip.
Add an https binding with your certificate to the site.

Step-by-step screenshots and command-line examples: Manual installation of the Core builds in IIS.

4. Start and set up MDriven Server

Start the application pools – MDriven Server first, then Turnkey.
Open MDriven Server in a browser at its address (for example https://myapp.example.com/__MDrivenServer/). On the first start it creates its own database in App_Data from the start database in the zip.
Log in to the administration pages and change the password of the user a – this is the account MDriven Turnkey uses to talk to the server. Use the same password in Turnkey: in App_Data/MDrivenServerOverride.xml (separate layout), or as MDrivenServerPWD in App_Data/TurnkeySettingsOverride.xml (default layout; settings in TurnkeySettings.xml are replaced when you update). See Change the MDriven Server password and Server administration.
Connect MDriven Server to the database that will hold your data, for example SQL Server – see Store the data in SQL Server.
Upload your model from MDriven Designer – see Connect your model to the server.
Open Turnkey at its address.

If something does not start, see An application does not start in IIS and Logs.

Updating to a new version

With the MDriven Installation Scripts: run them with the new zip names.
By hand: stop the application pool, unzip the new version over the application folder without deleting App_Data (it holds the settings and MDriven Server's database), and start the pool again. The program files are locked while the application runs, so stop it first.

Contents