ISAPI Deployment (IIS)

Deploy your Kitto^x application as an ISAPI DLL under Internet Information Services (IIS) on Windows Server.

When to use

• Enterprise Windows Server environments
• Integration with existing IIS infrastructure
• HTTPS termination and certificate management via IIS
• Windows Authentication pass-through to SQL Server

Prerequisites

• Windows Server with IIS role installed (or Windows 10/11 with IIS feature enabled)
• ISAPI Extensions and ISAPI Filters role services enabled in IIS
• Microsoft Visual C++ Redistributable installed on the server (required by Delphi Win64 executables)
• The ISAPI DLL compiled as Win64 (recommended) or Win32

Step 1: Compile the ISAPI DLL

Create a Delphi project (.dpr) for ISAPI deployment:

library MyAppISAPI;

uses
  Winapi.ActiveX,
  Web.WebBroker,
  Web.Win.ISAPIApp,
  Web.Win.ISAPIThreadPool,
  Kitto.WebBroker.WebModule,
  Controllers, Rules, UseKitto;

exports
  GetExtensionVersion,
  HttpExtensionProc,
  TerminateExtension;

begin
  CoInitFlags := COINIT_MULTITHREADED;
  Application.Initialize;
  Application.WebModuleClass := WebModuleClass;
  Application.Run;
end.

Compile in Release configuration for Win64.

UseKitto is required

The UseKitto unit is essential — it registers all framework controllers, authenticators, and tools. Without it, the DLL loads but no routes are registered and the application returns empty responses. Include Controllers and Rules if your application has custom business logic.

How it works

IIS loads the DLL and calls GetExtensionVersion / HttpExtensionProc for each request. WebBroker creates TWebRequest/TWebResponse pairs. TKWebModule delegates to TKWebBrokerHandler, which owns a TKWebEngine and calls SimpleHandleRequest. From this point on, the request pipeline is identical to the standalone server.

Step 2: Prepare the deployment folders

Kitto^x uses a two-level directory structure on the server:

• System Home — the framework engine, shared by all applications on the same server
• Application Home — the specific application (DLL, YAML metadata, resources)

At runtime, the framework first looks for files in the Application Home; if not found, it falls back to the System Home. This means you deploy the framework once and share it across multiple applications.

System Home (framework engine)

Create the framework folder and copy the contents of the KittoX\Home directory from the framework source:

C:\inetpub\KittoX\
  Home\
    Resources\             # Framework CSS, JS, icons, images
      css\
        kittox.css         # Core stylesheet
      js\
        htmx.min.js        # HTMX library
        kxgrid.js          # KittoX client-side helpers
        kxtabs.js          # Tab management
        kxsplitter.js      # Splitter
        kxfilters.js       # Filter panel
        kxtiles.js         # TilePanel helpers
        kxwizard.js        # Wizard helpers
        alpine.min.js      # AlpineJS
        suneditor.min.js   # HTML editor
        application.js     # Application-level JS (customizable)
        ...
      icons\               # Material Design SVG icons
        filled\
        outlined\
        round\
        sharp\
        two-tone\
    Templates\             # Page templates
      _Page.html           # Main HTML page template
      Login.html           # Login page template (optional override)

Application Home (your application)

Create a folder for each application under the KittoX root. Copy the compiled ISAPI DLL and the entire contents of your application's Home\ directory:

C:\inetpub\KittoX\App\HelloKitto\
  Home\
    HelloKittoISAPI.dll    # The compiled ISAPI DLL
    Metadata\
      Config.yaml          # Production configuration (DB, auth, theme)
      Models\              # Data model YAML files
      Views\               # UI definition YAML files
        Layouts\            # Form/grid layout YAML files
    Resources\             # Application-specific static files
      icons\               # Application-specific icons (optional)
      js\
        application.js     # Application-specific JS (optional)
        application.css    # Application-specific CSS (optional)
    Locale\                # Translation files (.po)
    ReportTemplates\       # Excel/PDF report templates (optional)

Multiple applications on the same server

With this structure, you can host multiple Kitto^x applications sharing the same framework engine:

C:\inetpub\KittoX\
  Home\                               # Shared framework (deployed once)
  App\
    HelloKitto\
      Home\                           # Application 1
        HelloKittoISAPI.dll
        Metadata\...
        Resources\...
    TasKitto\
      Home\                           # Application 2
        TasKittoISAPI.dll
        Metadata\...
        Resources\...
    MyProductionApp\
      Home\                           # Application 3
        MyAppISAPI.dll
        Metadata\...
        Resources\...

Each application has its own IIS Application (see Step 4) pointing to its folder, but they all share the framework resources from C:\inetpub\KittoX\Home\.

Production Config.yaml

Configure Config.yaml for production. Under IIS, the Server/Port and Server/ThreadPoolSize settings are ignored (IIS manages connections and threading).

Important: the AppPath setting must match the IIS Application alias exactly:

# AppPath must match the IIS alias (e.g. /hellokittox for alias "hellokittox")
AppPath: /hellokittox

DatabaseRouter:
  DatabaseName: Main
Databases:
  Main:
    Connection: FireDAC
      DriverId: MSSQL
      Server: db-server\SQLEXPRESS
      Database: MyDatabase

Auth: DB
Charset: utf-8

Log:
  Level: debug
  TextFile:
    FileName: %APP_PATH%.log
    IsEnabled: True

Diagnostic logging

Set Log/Level: debug during initial setup. The log file is created next to the DLL (e.g. C:\inetpub\KittoX\App\HelloKitto\Home\.log) and records the full request flow: URL parsing, route matching, session management. Change to detailed or low once everything works.

AppPath mismatch

If AppPath in Config.yaml does not match the IIS Application alias, all requests return empty or 500 errors. For example, if the IIS alias is hellokittox, Config.yaml must have AppPath: /hellokittox.

Step 3: Create an Application Pool

Open IIS Manager (inetmgr):

1. In the Connections pane, click Application Pools
2. In the Actions pane, click Add Application Pool...
3. Configure:
   • Name: KittoXPool
   • Managed Pipeline Mode: Classic (required for ISAPI)
   • .NET CLR Version: No Managed Code
4. Click OK

Now configure the pool — select KittoXPool, click Advanced Settings...:

Setting	Value	Reason
Enable 32-Bit Applications	False (Win64) or True (Win32)	Must match the DLL bitness
Identity	Custom account or NetworkService	Must have DB access and folder read permissions
Idle Time-out (minutes)	0	Prevents IIS from unloading the DLL when idle
Regular Time Interval (minutes)	0	Prevents periodic recycling that destroys sessions

Application Pool Recycling

By default, IIS recycles application pools every 1740 minutes (29 hours). This unloads the ISAPI DLL, destroying all in-memory sessions. Set Regular Time Interval to 0 to disable automatic recycling, or schedule recycling during off-hours via Specific Times.

Step 4: Create the IIS Site and Application

With IIS, each Kitto^x application is identified by its URL path (alias), not by a TCP port as in standalone mode. The Server/Port setting in Config.yaml is ignored — IIS manages ports via site bindings.

There are two common patterns:

Option A: Multiple apps under one site (recommended)

One IIS site hosts multiple Kitto^x applications, each as an IIS Application with its own alias. All apps share the same port and hostname; the alias differentiates them.

1. In IIS Manager, right-click Sites > Add Website...
2. Configure:
   • Site name: KittoX
   • Application pool: KittoXPool
   • Physical path: C:\inetpub\KittoX (the framework root)
   • Binding: port 80 (or 443 for HTTPS), hostname as needed
3. Click OK
4. Right-click the new site > Add Application...
5. Configure:
   • Alias: hellokitto → URL: http://server/hellokitto/
   • Application pool: KittoXPool
   • Physical path: C:\inetpub\KittoX\App\HelloKitto\Home
6. Click OK
7. Repeat for each additional application (e.g. alias taskitto, physical path ..\App\TasKitto\Home)

The alias becomes the AppPath that Kitto^x uses in all its URLs (e.g. /hellokitto/kx/view/...).

Shared framework resources

When IIS receives a request for /hellokitto/res/css/kittox.css, it looks first in the application's physical path (App\HelloKitto\Home\Resources\). If not found there, configure a Virtual Directory named res on the parent site pointing to C:\inetpub\KittoX\Home\Resources\ so that shared framework resources are served as fallback.

Option B: One site per app (isolated)

Each Kitto^x application gets its own IIS site with a dedicated port or hostname. Use this when you need complete isolation (separate Application Pools, separate bindings, separate SSL certificates).

1. In IIS Manager, right-click Sites > Add Website...
2. Configure:
   • Site name: HelloKitto
   • Application pool: HelloKittoPool (create a dedicated pool)
   • Physical path: C:\inetpub\KittoX\App\HelloKitto\Home
   • Binding: choose a dedicated port (e.g. 8081) or hostname (e.g. hellokitto.mycompany.com)
3. Click OK

In this mode, the Kitto^x AppPath is / (root of the site). Configure in Config.yaml:

AppPath: /

Option C: Application under Default Web Site (for testing)

The simplest option for quick testing:

1. Expand Sites > Default Web Site
2. Right-click > Add Application...
3. Configure:
   • Alias: hellokitto → URL: http://localhost/hellokitto/
   • Application pool: KittoXPool
   • Physical path: C:\inetpub\KittoX\App\HelloKitto\Home
4. Click OK

Step 5: Configure ISAPI Handler Mapping

1. Select your application in IIS Manager (e.g. hellokitto)
2. Double-click Handler Mappings
3. In the Actions pane, click Add Script Map...
4. Configure:
   • Request path: *
   • Executable: C:\inetpub\KittoX\App\HelloKitto\Home\HelloKittoISAPI.dll
   • Name: KittoXISAPI
5. Click Request Restrictions...:
   • Mapping tab: uncheck Invoke handler only if request is mapped to
   • Verbs tab: select All verbs
   • Access tab: select Execute
6. Click OK twice
7. When prompted "Do you want to allow this ISAPI extension?", click Yes
8. If the handler appears in the Disabled section of Handler Mappings, click Edit Feature Permissions... (in the Actions pane on the right) and enable Read, Script, and Execute

Step 6: Configure ISAPI Restrictions (Server-level)

1. In IIS Manager, select the server node (top level)
2. Double-click ISAPI and CGI Restrictions
3. Verify that C:\inetpub\KittoX\App\HelloKitto\Home\HelloKittoISAPI.dll appears with Allowed status
4. If not, click Add... and add the DLL path with Allow extension path to execute checked

Step 7: Set Folder Permissions

The Application Pool identity needs access to both the framework and the application folders:

Folder	Permission	Reason
C:\inetpub\KittoX\Home\	Read	Shared framework resources (CSS, JS, icons, templates)
C:\inetpub\KittoX\App\HelloKitto\Home\	Read & Execute	Load the ISAPI DLL, read YAML metadata and resources
C:\inetpub\KittoX\App\HelloKitto\Home\	Write (optional)	Only if the app writes log files or uploads

To set permissions via command line:

icacls "C:\inetpub\KittoX\Home" /grant "IIS AppPool\KittoXPool":(OI)(CI)R
icacls "C:\inetpub\KittoX\App\HelloKitto\Home" /grant "IIS AppPool\KittoXPool":(OI)(CI)RX

Step 8: Test

Open a browser and navigate to:

• Option A (multiple apps, one site): http://server/hellokitto/
• Option B (one site per app): http://server:8081/ or http://hellokitto.mycompany.com/
• Option C (Default Web Site): http://localhost/hellokitto/

You should see the Kitto^x login page.

Step 9: HTTPS (recommended for production)

1. Obtain an SSL certificate (Let's Encrypt, commercial CA, or self-signed for internal use)
2. In IIS Manager, select the site > Bindings...
3. Add an HTTPS binding (port 443) with the certificate
4. Optionally add a URL Rewrite rule to redirect HTTP to HTTPS

Troubleshooting

Issue	Solution
HTTP 403.1	The directory does not allow execution. Select the application in IIS Manager → Handler Mappings → Edit Feature Permissions → enable Read, Script, Execute
HTTP 500.19	Check folder permissions and web.config issues
HTTP 500.0	Check ISAPI restriction is "Allowed" and DLL bitness matches the pool
HTTP 500 "Class DB not found"	The .dpr is missing the UseKitto unit. Add UseKitto (and Controllers, Rules) to the uses clause and recompile
HTTP 500 "Configuration Error"	The diagnostic page shows AppHomePath and SystemHomePath — verify they point to the correct folders. Check that AppPath in Config.yaml matches the IIS virtual directory alias. Check webbroker_debug.log next to the DLL for initialization details
HTTP 200 empty body	The engine is not active or no routes are registered. Check the webbroker_debug.log file next to the DLL for initialization errors
HTTP 404	Check the handler mapping request path and DLL path
Blank page	Check Config.yaml exists in Home\Metadata\ and DB connection is correct
DLL fails to load	Install Visual C++ Redistributable; check 32/64 bit match
Sessions lost periodically	Disable Application Pool recycling (Regular Time Interval = 0)
Slow first request	The ISAPI DLL loads on first request; consider IIS Application Initialization for warm-up
Database connection fails	Check pool identity has DB access; for Windows Auth use NetworkService or domain account
Static files not served	IIS serves static files from the physical path automatically; check Home\Resources\ is accessible
Log file not created	Ensure the pool identity has write permission to the DLL folder. Check that Log/TextFile/IsEnabled: True in Config.yaml
Handler mapping disabled	In Handler Mappings, right-click the KittoXISAPI entry and verify it is in the "Enabled" section. Edit Feature Permissions to enable Execute

See also

• Deployment Overview — all deployment modes
• Web Server Configuration — .dpr examples and development setup
• Proxy Configuration — reverse proxy with Apache/nginx