Apache Module Deployment

Deploy your Kitto^x application as a native Apache module. The deployment structure mirrors the ISAPI (IIS) layout, making it easy to maintain both configurations for the same application.

When to use

Apache HTTP Server on Windows or Linux
Integration with existing Apache infrastructure
Environments where IIS is not available
Cross-platform hosting

Prerequisites

Apache HTTP Server 2.4 (64-bit recommended)
The module DLL compiled with the same bitness as Apache (Win64 or Win32)
Microsoft Visual C++ Redistributable on Windows

Step 1: Compile the Apache module DLL

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

pascal

library mod_hellokitto;

uses
  {$IFDEF MSWINDOWS}
  Winapi.ActiveX,
  System.Win.ComObj,
  {$ENDIF}
  Web.WebBroker,
  Web.ApacheApp,
  Web.HTTPD24Impl,
  Kitto.WebBroker.WebModule,
  Controllers, Rules, UseKitto;

var
  GModuleData: TApacheModuleData;

exports
  GModuleData name 'hellokitto_module';

begin
{$IFDEF MSWINDOWS}
  CoInitFlags := COINIT_MULTITHREADED;
{$ENDIF}
  Web.ApacheApp.InitApplication(@GModuleData);
  Application.Initialize;
  Application.WebModuleClass := WebModuleClass;
  Application.Run;
end.

Compile in Release configuration for Win64 (or matching your Apache bitness).

UseKitto is required

The UseKitto unit is essential — it registers all framework controllers, authenticators, and tools. Without it, the module loads but no routes are registered and the application returns empty responses.

Exports name

The exports name (hellokitto_module) must match the LoadModule directive in httpd.conf exactly.

Step 2: Prepare the deployment folders

The deployment structure is identical to the ISAPI (IIS) layout. Use the htdocs directory as the root:

System Home (framework engine)

Copy the contents of the KittoX\Home directory from the framework source:

D:\Apache24\htdocs\kittox\
  Home\
    Resources\             # Framework CSS, JS, icons, images
      css\
        kittox.css
      js\
        htmx.min.js
        kxgrid.js
        kxtabs.js
        ...
      icons\
        filled\
        outlined\
        ...
    Templates\
      _Page.html

Application Home (your application)

Copy the compiled DLL and the application's Home\ contents:

D:\Apache24\htdocs\kittox\
  App\
    HelloKitto\
      Home\
        mod_hellokitto.dll   # The compiled Apache module DLL
        Metadata\
          Config.yaml        # Production configuration
          Models\
          Views\
            Layouts\
        Resources\           # Application-specific static files
        Locale\              # Translation files (optional)
        ReportTemplates\     # Report templates (optional)

Multiple applications

Multiple Kitto^x applications share the same framework, each with its own DLL and Home:

D:\Apache24\htdocs\kittox\
  Home\                           # Shared framework (deployed once)
  App\
    HelloKitto\
      Home\                       # Application 1
        mod_hellokitto.dll
        Metadata\...
    TasKitto\
      Home\                       # Application 2
        mod_taskitto.dll
        Metadata\...

Production Config.yaml

The AppPath must match the <Location> directive in httpd.conf. The Server/Port and Server/ThreadPoolSize settings are ignored (Apache manages connections and threading):

yaml

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

AppPath mismatch

If AppPath in Config.yaml does not match the <Location> path in httpd.conf, all requests will fail. For example, if the Location is /hellokittox, Config.yaml must have AppPath: /hellokittox.

Step 3: Configure httpd.conf

Add the following to your Apache configuration (D:\Apache24\conf\httpd.conf). Use Define directives to avoid repeating paths:

Single application

apache

# ===== KittoX Framework =====
Define KITTOX_ROOT "D:/Apache24/htdocs/KittoX"

# ===== HelloKitto Application =====
Define KITTOX_HELLOKITTO_HOME "${KITTOX_ROOT}/App/HelloKitto/Home"
LoadModule hellokitto_module "${KITTOX_HELLOKITTO_HOME}/mod_hellokitto.dll"
<Location /hellokittox>
    SetHandler mod_hellokitto-handler
</Location>

That's it. No RewriteRule, no <Directory>, no mod_rewrite needed.

Multiple applications

Add a block for each application, reusing KITTOX_ROOT:

apache

# ===== TasKitto Application =====
Define KITTOX_TASKITTO_HOME "${KITTOX_ROOT}/App/TasKitto/Home"
LoadModule taskitto_module "${KITTOX_TASKITTO_HOME}/mod_taskitto.dll"
<Location /taskittox>
    SetHandler mod_taskitto-handler
</Location>

How static resources are served

Kitto^x serves static files (CSS, JS, icons, images) internally via TKMultipleStaticWebRoute. No Apache configuration is required for /res/* URLs.

The resolution order is:

App Resources: App/{AppName}/Home/Resources/ (e.g. application.css, custom icons)
Framework Resources: Home/Resources/ (e.g. kittox.css, htmx.min.js, Material Design Icons)

Delegating resources to Apache

If you prefer Apache to serve static files directly (e.g. for performance), set Application/HandleResources: False in Config.yaml and configure Alias or RewriteRule manually. The default (True) works out of the box.

Trailing slash redirect

The module automatically redirects http://server/hellokittox (without trailing slash) to http://server/hellokittox/. This is essential because the HTML uses relative URLs (e.g. kx/login) which the browser resolves based on the current page path.

Step 4: Set permissions

Ensure the Apache service account has access to the deployment folders:

Folder	Permission	Reason
`htdocs\kittox\Home\`	Read	Shared framework resources
`htdocs\kittox\App\HelloKitto\Home\`	Read & Execute	Load the DLL, read YAML metadata
`htdocs\kittox\App\HelloKitto\Home\`	Write (optional)	Log files, file uploads

On Windows, Apache typically runs as NetworkService or Local System. On Linux, as www-data or apache.

Step 5: Restart Apache

batch

:: Windows — restart the Apache service
httpd -k restart

:: Or if running as a Windows service
net stop Apache2.4
net start Apache2.4

bash

# Linux
sudo systemctl restart apache2

Reloading after DLL changes

Apache keeps the module DLL loaded in memory. To deploy a new version, you must stop Apache completely, replace the DLL, then start Apache again. A simple restart may not release the file lock on Windows.

Step 6: Test

Open a browser and navigate to:

http://localhost/hellokittox/

You should see the Kitto^x login page. Adjust the port if Apache is configured on a non-standard port (e.g. http://localhost:8080/hellokittox/).

Step 7: HTTPS (recommended for production)

Enable mod_ssl in httpd.conf (uncomment LoadModule ssl_module)
Configure a <VirtualHost *:443> block with your SSL certificate:

apache

<VirtualHost *:443>
    ServerName myserver.example.com
    SSLEngine on
    SSLCertificateFile "conf/ssl/server.crt"
    SSLCertificateKeyFile "conf/ssl/server.key"
</VirtualHost>

The <Location> directives defined in the main server context are automatically inherited by VirtualHosts — no need to duplicate them inside the <VirtualHost> block.

Configuration notes

Threading is managed by Apache, not by Indy. The Server/Port and Server/ThreadPoolSize settings in Config.yaml are ignored.
Session timeout and cleanup are managed by TKWebEngine as usual.
The %APP_PATH% macro in Config.yaml expands to the DLL directory (e.g. D:\Apache24\htdocs\kittox\App\HelloKitto\Home\).
The framework System Home is found automatically via the relative path ..\..\..\..\Home\ from the DLL location.
Static resources are served by the module internally. The Application/HandleResources setting (default True) controls this behavior.

Troubleshooting

Issue	Solution
Module fails to load	Check the DLL path in `LoadModule` (use forward slashes). Check Apache bitness matches the DLL (32/64 bit). Check Apache error log: `logs/error.log`
HTTP 500	Check `error.log` for details. Common cause: missing Visual C++ Redistributable
HTTP 500 "Class DB not found"	The `.dpr` is missing `UseKitto`. Recompile with `UseKitto` in the uses clause
HTTP 500 "Configuration Error"	Check `AppPath` in Config.yaml matches the `<Location>` path. Check `webbroker_debug.log` and `%APP_PATH%.log` next to the DLL for diagnostic details
Empty response	The engine may not be active or routes not registered. Check the log file next to the DLL
Sessions lost	Apache worker recycling unloads the module. Set `MaxRequestsPerChild 0` in `httpd.conf` to disable worker recycling
Database connection fails	Ensure the Apache service account has DB access. For Windows Auth, run Apache as a domain user
DLL file locked during update	Stop Apache completely (`httpd -k stop`), replace the DLL, then start (`httpd -k start`)
Log file not created	Check that the Apache service account has write permission to the DLL folder. Ensure `Log/TextFile/IsEnabled: True` and `Log/Level` are set in Config.yaml
Apache won't start after adding module	Check `error.log`. Common cause: DLL built for wrong Apache version (2.2 vs 2.4) or wrong bitness

Deployment

Layout & Containers

Navigation

Data Display

Data Editing

Enterprise

Authentication

Tool Controllers

Apache Module Deployment

When to use

Prerequisites

Step 1: Compile the Apache module DLL

Step 2: Prepare the deployment folders

System Home (framework engine)

Application Home (your application)

Multiple applications

Production Config.yaml

Step 3: Configure httpd.conf

Single application

Multiple applications

How static resources are served

Trailing slash redirect

Step 4: Set permissions

Step 5: Restart Apache

Step 6: Test

Step 7: HTTPS (recommended for production)

Configuration notes

Troubleshooting

See also

Apache Module Deployment ​

When to use ​

Prerequisites ​

Step 1: Compile the Apache module DLL ​

Step 2: Prepare the deployment folders ​

System Home (framework engine) ​

Application Home (your application) ​

Multiple applications ​

Production Config.yaml ​

Step 3: Configure httpd.conf ​

Single application ​

Multiple applications ​

How static resources are served ​

Trailing slash redirect ​

Step 4: Set permissions ​

Step 5: Restart Apache ​

Step 6: Test ​

Step 7: HTTPS (recommended for production) ​

Configuration notes ​

Troubleshooting ​

See also ​

Apache Module Deployment

When to use

Prerequisites

Step 1: Compile the Apache module DLL

Step 2: Prepare the deployment folders

System Home (framework engine)

Application Home (your application)

Multiple applications

Production Config.yaml

Step 3: Configure httpd.conf

Single application

Multiple applications

How static resources are served

Trailing slash redirect

Step 4: Set permissions

Step 5: Restart Apache

Step 6: Test

Step 7: HTTPS (recommended for production)

Configuration notes

Troubleshooting

See also