How do I install Livecode Server with IIS on Windows (plus workaround for error 502 bad gateway)
The LiveCode Server product brings english like language to the server environment. The server engine is a separate build of the LiveCode engine with specific syntax and functionality that makes it suitable for use in command-line contexts and, in particular, as a CGI processor.
This lesson will walk you through the steps required to install LiveCode Server on Windows with IIS (Internet Information Services).
For this lesson we used a Windows 11 PC, but the steps should be identical for Windows 10 and also for Windows Server 2016 and up.
Important Note: With Livecode Server versions 7 to 9.6.10 IIS on Windows 10 and up and Server 2016 and up returns "error 502 bad gateway with IIS"
This is because those Livecode Server versions expect IIS to define a environment variable DOCUMENT_ROOT.
But this variable is not defined by IIS and therefore Livecode Server quits before executing the script.
There is an easy workaround for this. See chapter 3.1
Since version 9.6.11RC1 this is fixed and the workaround in chapter 3.1 is not needed anymore.
Download the free Notepad++ Editor. https://notepad-plus-plus.org/downloads/ and install it.
This is not required, but recommended if you only have Notepad from Microsoft installed. Please do not use Microsoft Notepad for the described editing tasks.
Open Control Panel and click on Programs
In the new window
- click on Turn Windows features on or off (1)
In the new pop-up window
- click the + left from on Internet Information Services (2)
- click the + left from on Web Management Tools (3)
- enable IIS Management Console (4)
- click the + left from on Application Development Features (1)
- enable CGI (2)
- click the + left from on Common HTTP Features (1)
and enable all options as seen in the screenshot above (2)
- click the + left from on Health and Diagnostics (1)
and enable the option Tracing (2)
Close that windows by clicking on OK. Internet Information Services will now be installed.
Now open your browser and enter localhost in the URL field and press return. You should see the above page in your browser.
If you see an error message instead of the above page then something went wrong with the installation of IIS. Please check again the steps in chapter 1.2 and make sure that the installation went through without an error message.
Download Livecode Server/Livecode Server Pro. You'll find the downloads in your Livecode account at https://livecode.com/account/products/livecode/
and unzip it.
Open C:\inetpub\wwwroot in Windows Explorer
and create a folder cgi-bin. (1)
Copy the unzipped Livecode Server files and folders to that cgi-bin folder.
For this lesson i created an extra folder livecode-server-9_6_10 (1) and copied the folders drivers and externals and the 2 files livecode-server-pro.exe and revpdfprinter.dll to it .
Open the "Internet Information Services (IIS) Manager" app
In IIS Manager click on server pane and expand it (1)
Click on Sites to expand it (2)
Click on Default Web Site (3)
Right click on Handler Mappings feature. (4)
In the context menu click Open Features
Right click in the new window and select Add Script Map... in the context menu (1)
Then in the new pop window
enter *.lc in the field Request path (2)
in Executable field, press the ... button (3) and in the upcoming file dialog select your livecode-server exe from your cgi-bin folder (4) and click the open button.
If you just see the 2 folders and the .dll file, then make sure the the (*.exe) is selected in the option field. (5)
In the Name field enter a name for this mapping, for example livecode-server. You can use whatever name you want. (6)
Press OK button (7)
In the upcoming Window press Yes to allow the new extension.
In Notepad++ or any other text editor create the below script and save it to c:\inetpub\wwwroot\lctest.lc
<?lc put "put the version" ?>
If you get an error when saving the script to the wwwroot folder saying that you do not have the permission to do so, then you have to adjust the permissions of the folder wwwroot for your user account.
To test the scrip open your web browser and enter http://localhost/lctest.lc
You should see a something similar to the output below.
Congratulations! Livecode Server is now ready to be used with IIS.
If you see a Gateway 502 error then see chapter 3.1
This problem occurs with Livecode Server 7 to 9.6.10.
The problem here is that IIS does not define the DOCUMENT_ROOT environment variable which will currently cause the livecode server engine to quit on startup when run in cgi mode.Future versions of Livecode Server will not have this dependence.
There is a workaround which will solve this for versions 7 - 9.6.10.
Just add a DOCUMENT_ROOT as system environment variable under System Properties.
To do this
in the Command prompt or in the 'Open Run' (WIN-R) (1) and press then Environment Variables. (2)
Click on New... below the System variables area (3)
In the new window enter
DOCUMENT_ROOT in the field Variable name (4)
and enter the path to the root folder of the default website. This is also the path where you've created the cgi-bin folder. In our lesson it is c:\inetpub\wwwroot (5)
Press OK button to add the new environment variable. (6)
After that restart your computer.
The error 502 should not occur anymore.