How-To: Deploy Your RAD Server Project On Windows With IIS

by Jim McKeethJun 3, 2019

This guide walks you through setting up RAD Server on IIS and deploying your project into production. It was written by Eli M. and is part of the collection of New RAD Server (EMS) Articles, Resources, and eBook.

What is RAD Server?

RAD Server is an easy to develop, deploy, and operate solution for ISVs and OEMs building REST API endpoints. It includes many great features such as multi-tiered development, on-premise or cloud deployments, and built-in services such as user management, push notifications, user location tracking, and built-in data storage. RAD Server can be deployed in production on both Windows and Linux. On Windows, RAD Server can run through IIS as an ISAPI library.

You can either configure IIS manually using the instructions found in the DocWiki under Installing the RAD Server or the RAD Server Console on a Production Environment on Windows or use the provided Delphi console app and Powershell script to pack up the needed files and automatically setup up a new website and application specifically for RAD Server. Prior to configuring IIS you should install the RAD Server Database (powered by InterBase).

There are five steps to deploy your RAD Server projects on Windows:

Installing InterBase on Windows
Packaging Up the Required Files
Creating New RAD Server Website Directories For IIS
Configuring IIS For RAD Server With Windows PowerShell
Deploying Custom Resource Modules

Installing InterBase on Windows

The RAD Server Database will need to be installed by installing InterBase on the Windows machine. Instructions for installing InterBase are available here: InterBase Quick Start: Part I – Installing InterBase for Windows and Installation, Registration, and Licensing Information. Once you have the InterBase ZIP file on your Windows machine, unzip the InterBase_2017_EN.zip file to a temporary directory. Change to the new InterBase directory and run install_windows.exe to install InterBase. You can keep all of the default options during installation.

For a RAD Server production environment, you do not add a normal InterBase license. Instead you will need to install your RAD Server license into InterBase to be able to run RAD Server in production through IIS. You can run the License Manager tool from the Windows Start menu in the Embarcadero InterBase 2017 folder to add your RAD Server license. Also be sure that RAD Server Database is running at this point by opening the InterBase Server Manager and checking the status. If it is not running, you can start it.

Package Up The Required Files For RAD Server In IIS

The RADServerWindowsPack code below is a Delphi Windows console application. You can paste this code into a new Delphi Windows Console app in RAD Studio.

program RADServerWindowsPack;

{$APPTYPE CONSOLE}

{$R *.res}

uses
  System.SysUtils,
  System.Zip;

const
   RADStudioPath = 'C:Program Files (x86)EmbarcaderoStudio20.0'</span>;

procedure CreateRADServerWindowsInstall(APath, AZipFile, AObjReposZipFile: String</span>);
begin
  var Zip := TZipFile.Create;
  try
    var RADStudioBinPath := APath;
    var EMSPath := 'C:UsersPublicDocumentsEmbarcaderoEMS'</span>;

    if not FileExists(AObjReposZipFile) then
      Zip.ZipDirectoryContents(AObjReposZipFile,RADStudioPath+'ObjReposenEMS'</span>);

    Zip.Open(AZipFile, zmWrite);

    Zip.Add(APath+'borlndmm.dll'</span>);
    Zip.Add(APath+'CustomIPTransport260.bpl'</span>);
    Zip.Add(APath+'dbrtl260.bpl'</span>);
    Zip.Add(APath+'EMSDevServer.exe'</span>);
    Zip.Add(APath+'EMSDevConsole.exe'</span>);
    Zip.Add(APath+'EMSConsole.dll'</span>);
    Zip.Add(APath+'EMSServer.dll'</span>);
    Zip.Add(APath+'emsserverapi260.bpl'</span>);
    Zip.Add(APath+'FireDAC260.bpl'</span>);
    Zip.Add(APath+'FireDACCommon260.bpl'</span>);
    Zip.Add(APath+'FireDACCommonDriver260.bpl'</span>);
    Zip.Add(APath+'FireDACIBDriver260.bpl'</span>);
    Zip.Add(APath+'FireDACSqliteDriver260.bpl'</span>);
    Zip.Add(APath+'IndyCore260.bpl'</span>);
    Zip.Add(APath+'IndyIPClient260.bpl'</span>);
    Zip.Add(APath+'IndyIPCommon260.bpl'</span>);
    Zip.Add(APath+'IndyProtocols260.bpl'</span>);
    Zip.Add(APath+'IndySystem260.bpl'</span>);
    Zip.Add(APath+'inet260.bpl'</span>);
    Zip.Add(APath+'rtl260.bpl'</span>);
    Zip.Add(APath+'vcl260.bpl'</span>);
    Zip.Add(APath+'vcldb260.bpl'</span>);
    Zip.Add(APath+'vclFireDAC260.bpl'</span>);
    Zip.Add(APath+'vclx260.bpl'</span>);
    Zip.Add(APath+'xmlrtl260.bpl'</span>);
  finally
    Zip.Free;
  end
end</span>;

begin
  try
    CreateRADServerWindowsInstall(RADStudioPath+'bin','RADServer_x86.zip', 'ObjReposEMS.zip'</span>);
    CreateRADServerWindowsInstall(RADStudioPath+'bin64','RADServer_x64.zip', 'ObjReposEMS.zip'</span>);
  except
    on E: Exception do
      Writeln(E.ClassName, ': ', E.Message);
  end</span>;
end.

Run the Console app to generate a ZIP file containing the needed RAD Server files and packages for a RAD Server Windows deployment:

It will generate a ZIP file for both 32-bit and 64-bit versions of EMSServer.dll.
An ObjReposEMS.zip file that contains files which you will need in order for EMSDevServer.exe to run.

You can see how easy it is in the RADServerWindowsPack code to work with ZIP files from within RAD Studio.

Create New RAD Server Website Directories For IIS

Copy the RADServer_x86.zip, RADServer_x64.zip, and ObjReposEMS.zip files to your Windows server. Next, create the following directories:

C:inetpubRADServer
C:inetpubRADServeremsserver
C:inetpubRADServerObjRepos
C:inetpubRADServerObjReposEMS

Depending on which version (either 32-bit or 64-bit) you want to use, you can unzip the files from RADServer_x86.zip or RADServer_x64.zip to the newly created C:inetpubRADServeremsserver directory.

Unzip the files from ObjReposEMS.zip to the C:inetpubRADServerObjReposEMS directory. There should now be a file called EMSDevServer.exe in the C:inetpubRADServeremsserver directory. Execute the EMSDevServer.exe file and it should prompt you with a dialog box that states “EMS server configuration file not found. Choose “Yes” to run the configuration wizard.”. Choose the default options for each section in the configuration wizard and press Finish at the end to finalize the creation of the C:UsersPublicDocumentsEmbarcaderoEMSemsserver.ib and C:UsersPublicDocumentsEmbarcaderoEMSemsserver.ini files.

Copy the C:UsersPublicDocumentsEmbarcaderoEMSemsserver.ini file to the C:inetpubRADServeremsserver directory where it will be next to the EMSServer.dll file. At this point you can also remove the C:inetpubRADServerObjRepos directory and its contents.

Configure IIS For RAD Server With Windows PowerShell

All of the needed files should be in place now to run RAD Server from within IIS. For the next step you will need to run a PowerShell script which you can do from within Windows PowerShell.

Click the Start menu in Windows
Type PowerShell
Right click on Windows PowerShell
Finally click Run as Administrator

Once you have the PowerShell command prompt open you can either run the below script by pasting it into the PowerShell window or you can create a reusable script by pasting the script into Windows Notepad, saving it as RADServerConfigIIS.ps1, and then executing the script from the PowerShell command prompt: .RADServerConfigIIS.ps1

#Set location of your site. 
$SiteName = "RADServer"
$Port = "8080"
$DriveSitePath = ("$env:systemdriveinetpub"+$SiteName)
$AppPool = $SiteName
$IISEMSPath = "IIS:sites"+$SiteName+"emsserver"
$DriveEMSPath = $DriveSitePath+"emsserver"
$DLLPath = $DriveEMSPath+"EMSServer.dll"

#Create an application pool and website 
New-WebAppPool -Name $AppPool
New-WebSite -Name $SiteName -Port $Port -PhysicalPath $DriveSitePath -ApplicationPool $AppPool

# Allow EMS website to override server-wide handler configurations
Set-WebConfiguration //System.webServer/handlers -metadata overrideMode -value Allow -PSPath IIS:/ -verbose

# Allow execute permissions for the EMS handler
Set-WebConfiguration -filter "/system.webServer/handlers/@AccessPolicy" -PSPath $IISEMSPath -value "Read, Script, Execute" -verbose

# Set up the EMS handler
Set-WebHandler -Name "ISAPI-dll" -Path "*.dll" -PSPath $IISEMSPath -RequiredAccess Execute -ScriptProcessor $DLLPath -ResourceType File -Modules IsapiModule -Verb '*'

# Create the EMS web app
New-WebApplication -Name "emsserver" -Site $SiteName -PhysicalPath $DriveEMSPath -ApplicationPool $AppPool

# Add exception to ISAPI and CGI Restrictions
Add-WebConfiguration -pspath 'MACHINE/WEBROOT/APPHOST' -filter "system.webServer/security/isapiCgiRestriction" -value @{description='
emsserverRestriction'</span>;path=$DLLPath;allowed='True'}

# Enable 32-bit applications
set-itemProperty IIS:apppools$AppPool -name "enable32BitAppOnWin64" -Value "true"

# Optional: Allow CORS
#Add-WebConfigurationProperty //system.webServer/httpProtocol/customHeaders  $IISEMSPath -AtIndex 0 -Name collection -Value @{name='Access-Control-Allow-Origin';value='*'}
#

Let’s walk through the PowerShell script above which creates a RAD Server website and application within IIS. In the first section we create a variable named $SiteName which corresponds to the site name in IIS. The $Port variable is the port you want the site to run on and the script defaults to port 8080. The $DriveSitePath variable is the path to your C:inetpubRADServer directory. The $AppPool variable is set to the $SiteName variable. The $IISEMSPath variable is a path to your emsserver directory within IIS. The $DriveEMSPath variable contains the path to your C:inetpubRADServeremsserver directory. And finally, $DLLPath contains the path to your C:inetpubRADServeremsserverEMSServer.dll file.

New-WebAppPool creates a new application pool for the new website. New-WebSite creates the new website using the name set in the script. The two Set-WebConfiguration commands set up an access policy to allow the WebHandler that the script will create to run correctly. The Set-WebHandler command modifies the ISAPI-dll web handler in IIS within the emsserver directory and configures it to point at your EMSServer.dll file. The New-WebApplication command turns the emsserver directory into a new application using the new application pool. The Add-WebConfiguration command modifies the ISAPI and CGI Restrictions section at the root of your IIS configuration to add the EMSServer.dll as an allowed ISAPI. Finally, set-itemProperty sets the enable32BitAppOnWin64 setting on the Application Pool to True.

The final command in the script is optional and disabled by default. The Add-WebConfigurationProperty command adds the Access-Control-Allow-Origin header to your emsserver application. This header can also be configured from within emsserver.ini. Be sure to only add this header in one place because otherwise your web server could be sending the same Access-Control-Allow-Origin header twice.

If everything has been configured correctly you should be able to visit http://localhost:8080/emsserver/EMSServer.dll/version in your web browser and receive a JSON response from RAD Server.

Deploy Custom Resource Modules

You can add your own custom resource modules by copying them to the C:inetpubRADServeremsserver directory. Edit the C:inetpubRADServeremsserveremsserver.ini file and add your custom resource module to the Server.Packages section like you can see below:

[Server.Packages]


C:inetpubRADServeremsserverProject1.bpl=My Project1 Resource Module

Summary

With that your RAD Server is setup and your module is deployed. The following links have more information to help you along the path on your RAD Server journey.

The Complete Guide to RAD Server eBook by David I. (only available to RAD Server Enterprise and Architect customers)
Mobilizing your Business with Enterprise Mobility Services Middleware by Cary Jensen (webinar, whitepaper, and code)
New RAD Server (EMS) Articles, Resources, and eBook
Installing the RAD Server or the RAD Server Console on a Production Environment on Windows
InterBase Quick Start: Part I – Installing InterBase for Windows
Installation, Registration, and Licensing Information