Friday, May 17, 2013

Using Apex with IIS Express

The Thoth Gateway is a gateway written in C# and ASP.NET that allows you to run PL/SQL web applications (including Oracle Application Express) on Microsoft's Internet Information Server (IIS). You can read more about the gateway here. It is an alternative to Apache/mod_plsql and the Java-based Apex Listener.

For production deployment on a server, you should use a regular IIS installation. However, if you are a developer working on a local Apex installation on your laptop, then the full IIS package is more than you need. Microsoft also offers a lightweight alternative in IIS Express:

IS Express (...) will run on Windows XP and higher systems, does not require an administrator account, and does not require any code changes to use.
You might want to take a look at this nice video with lots of information about IIS Express.

Using the Thoth Gateway with IIS Express is in many ways similar to running the Apex Listener in Standalone mode. Here's how to use the Thoth Gateway with IIS Express on your development machine.

Download and Install IIS Express

Download the IIS Express installer from Microsoft's website.

Run the installer.

This will put the IIS Express software under C:\Program Files\IIS Express and the configuration files under C:\Documents and Settings\Administrator\My Documents\IISExpress (assuming you are running Windows XP and your username is Administrator).

Configure IIS Express

Open \My Documents\IISExpress\config\applicationhost.config and add a new site under the "sites" node:

Copy and paste the following:

                <application path="/" applicationPool="Clr2IntegratedAppPool">
                    <virtualDirectory path="/i" physicalPath="C:\temp\apex_4.1.1_en\apex\images" />
                    <virtualDirectory path="/" physicalPath="C:\temp\apex_4.1.1_en\apex\images" />

                <application path="/web" applicationPool="Clr2IntegratedAppPool">
                    <virtualDirectory path="/" physicalPath="c:\temp\thoth_iisexpress" />

                    <binding protocol="http" bindingInformation=":8090:localhost" />

Some points to note:
  • This configuration sets up the virtual directories to serve the Apex images (in the "i" folder) and to run the actual gateway application (the "web" folder, which in mod_plsql is usually called "pls", but you can call it whatever you want). Both the images and the ASP.NET application are placed under c:\temp (but you can place them wherever you want).
  • The port number is set to 8090.
  • The traceFailedRequestsLogging has been disabled to improve speed.

For better performance with static files, you should also add a httpExpires value to the clientCache setting:

        <!-- see -->
        <clientCache httpExpires="Sun, 29 Mar 2030 00:00:00 GMT" cacheControlMode="UseExpires" />

Download and Install the Thoth Gateway

Download the Thoth Gateway and unzip the file.

Instead of following the normal installation instructions (which assume a full IIS installation), simply create a folder (I've used c:\temp\thoth_iisexpress in the example above) and copy the web.config and the bin folder from the unzipped file to this location.

Create a shortcut to start IIS Express

Now we just need a convenient way to start IIS Express whenever we want to do Apex work.

Create a batch file (I've called it start_iisexpress.bat) and put the following command in it:

"c:\program files\iis express\iisexpress.exe" /siteid:2 /systray:true

Create a shortcut to this batch file on your Windows desktop, and double-click the shortcut to start IIS Express.

As long as IIS Express is running, a console window will show each request:

That's it, you now have a lightweight, local web server for working with Oracle Application Express on a Windows machine.


If you need to troubleshoot the installation, you should enable the traceFailedRequestsLogging (see above). You'll find the trace files under \My Documents\IISExpress\TraceLogFiles. When you are done, disable this setting again for better performance.

Also note that all configuration changes to IIS Express require you to restart IIS Express before they take effect.


Anonymous said...

Hello Morten, Congratulations for your great work, we have been using Thoth in a production environnement since it allows us to use IIS and integrated Kerberos authentication.

We are testing the new apex 4.2.2 version with the thoth gateway and encountering some weird behaviour related to database exception handling. It does not happen when we do not use thoth, or when we use an apex version prior to 4.2.2. Have you encountered that ?

Morten Braten said...

@Alain: Not much to report on this issue yet, but it is being tracked here:

- Morten