Skip to main content

​
Installation

This guide covers all methods of installing Horse in your Delphi or Lazarus project, from the recommended Boss package manager to manual installation.

​
System Requirements

Delphi

Supported Versions:
  • Delphi 13 Florence
  • Delphi 12 Athens
  • Delphi 11 Alexandria
  • Delphi 10.4 Sydney
  • Delphi 10.3 Rio
  • Delphi 10.2 Tokyo
  • Delphi 10.1 Berlin
  • Delphi 10 Seattle
  • Delphi XE8
  • Delphi XE7

Lazarus

Supported Versions:
  • Lazarus 2.0+
  • Free Pascal 3.0+
Platforms:
  • Windows
  • Linux
  • macOS
Boss is a dependency manager for Delphi and Lazarus that makes installing Horse and its dependencies simple.
1

Install Boss

If you don’t have Boss installed:Windows:
# Download and run the installer from:
# https://github.com/HashLoad/boss/releases
Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/HashLoad/boss/master/scripts/install.sh | sh
2

Install Horse

Open a terminal in your project directory and run:
boss install horse
Boss will automatically:
  • Download Horse and its dependencies
  • Configure library paths
  • Update your project settings
3

Verify Installation

Check that Horse was installed:
boss list
You should see horse in the list of installed packages.
Boss automatically manages dependencies and keeps packages up to date. This is the recommended installation method.

​
Method 2: Manual Installation

For manual installation without a package manager:
1

Download Horse

Clone or download Horse from GitHub:
git clone https://github.com/HashLoad/horse.git
Or download the ZIP file from the releases page.
2

Add to Library Path (Delphi)

  1. Open Delphi IDE
  2. Go to Tools > Options
  3. Navigate to Language > Delphi > Library
  4. Select your target platform (e.g., Windows 32-bit)
  5. Click the […] button next to “Library path”
  6. Add the path to Horse’s src folder: 
    C:\path\to\horse\src
  7. Click OK to save
3

Add to Search Path (Lazarus)

  1. Open Lazarus IDE
  2. Go to Project > Project Options
  3. Navigate to Compiler Options > Paths
  4. In “Other unit files (-Fu)” add: 
    /path/to/horse/src
  5. Click OK to save
4

Add Horse to Uses Clause

In your project, add Horse to the uses clause:
uses
  Horse;

​
Method 3: Git Submodule

For projects using Git, you can add Horse as a submodule: 
# Add Horse as a submodule
git submodule add https://github.com/HashLoad/horse.git lib/horse

# Initialize and update submodules
git submodule update --init --recursive
Then add lib/horse/src to your library path as described in Method 2.

​
Installing Middleware

Horse has a rich ecosystem of middleware packages. Here’s how to install them:

​
Using Boss

# JSON support
boss install jhonson

# CORS
boss install horse-cors

# JWT Authentication
boss install horse-jwt

# Basic Authentication
boss install horse-basic-auth

# Logging
boss install horse-logger

# Compression
boss install horse-compression

# Exception Handling
boss install handle-exception

# Stream Support
boss install horse-octet-stream

​
Manual Installation

For each middleware:
  1. Clone the repository
  2. Add the src folder to your library path
  3. Add the middleware unit to your uses clause
Example for CORS: 
git clone https://github.com/HashLoad/horse-cors.git
Add to library path: horse-cors/src Use in code: 
uses
  Horse,
  Horse.CORS;

begin
  THorse.Use(CORS);
  // ... rest of your code
end.

​
Project Configuration

​
Delphi Console Application

  1. Create a new Console Application
  2. Add Horse to the uses clause
  3. Add {$APPTYPE CONSOLE} directive
program MyServer;

{$APPTYPE CONSOLE}

uses
  Horse,
  System.SysUtils;

begin
  // Your Horse code here
end.

​
Delphi VCL Application

  1. Create a new VCL Forms Application
  2. Add Horse to the uses clause
  3. Important: Add HORSE_VCL to project defines:
    • Go to Project > Options
    • Navigate to Delphi Compiler > Compiling
    • In “Conditional defines” add: HORSE_VCL
uses
  Horse;

// In your form's button click handler:
procedure TForm1.btnStartClick(Sender: TObject);
begin
  THorse.Listen(9000);
end;

​
Delphi ISAPI Application

  1. Create a new Web Broker Application
  2. Choose ISAPI Dynamic Link Library
  3. Add HORSE_ISAPI to project defines
  4. Add Horse to the uses clause
library MyISAPI;

uses
  Horse;

{$R *.res}

begin
  // Horse automatically handles ISAPI requests
  THorse.Get('/api/ping',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Send('pong');
    end);
end.

​
Lazarus Console Application

  1. Create a new Program
  2. Add mode directive: {$MODE DELPHI}{$H+}
  3. Add Horse to the uses clause
program MyServer;

{$MODE DELPHI}{$H+}

uses
  Horse;

begin
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Send('pong');
    end);
  
  THorse.Listen(9000);
end.

​
Lazarus Daemon

  1. Create a new Program
  2. Add HORSE_DAEMON to project defines
  3. Add Horse to the uses clause
program MyDaemon;

{$MODE DELPHI}{$H+}

uses
  Horse;

begin
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Send('pong');
    end);
  
  THorse.Listen(9000);
end.

​
Compilation Directives

Horse uses compilation directives to support different deployment scenarios:
DirectivePurposePlatform
HORSE_VCLVCL application supportDelphi (Windows)
HORSE_ISAPIISAPI moduleDelphi (Windows)
HORSE_APACHEApache moduleDelphi/Lazarus
HORSE_CGICGI applicationDelphi/Lazarus
HORSE_FCGIFastCGI applicationLazarus
HORSE_DAEMONDaemon/ServiceDelphi/Lazarus
HORSE_LCLLCL applicationLazarus

​
Adding Compilation Directives

Delphi:
  1. Project > Options
  2. Delphi Compiler > Compiling
  3. Add to “Conditional defines”
Lazarus:
  1. Project > Project Options
  2. Compiler Options > Custom Options
  3. Add: -dHORSE_VCL (or other directive)

​
Verification

Create a simple test to verify Horse is working: 
program TestHorse;

{$APPTYPE CONSOLE}

uses
  Horse,
  System.SysUtils;

begin
  try
    Writeln('Horse Version: ', THorse.Version);
    
    THorse.Get('/test',
      procedure(Req: THorseRequest; Res: THorseResponse)
      begin
        Res.Send('Horse is working!');
      end);
    
    THorse.Listen(9000,
      procedure
      begin
        Writeln('Server running on port 9000');
        Writeln('Test: http://localhost:9000/test');
        Writeln('Press Enter to stop...');
        Readln;
      end);
  except
    on E: Exception do
      Writeln('Error: ', E.Message);
  end;
end.
Run this program and navigate to http://localhost:9000/test in your browser. You should see “Horse is working!”.

​
Optional: Install Horse Wizard

The Horse Wizard is an IDE wizard that helps you create Horse projects quickly: 
boss install horse-wizard
After installation, restart your IDE. You’ll find new project templates under File > New > Other > Horse.

​
Troubleshooting

Solution:
  • Verify the Horse src folder is in your library path
  • Restart the IDE after adding the path
  • Check that the path is correct for your target platform
Solution:
  • For VCL applications, ensure HORSE_VCL is defined
  • For ISAPI, ensure HORSE_ISAPI is defined
  • Check that you’re using the correct provider for your project type
Solution:
  • Check your internet connection
  • Verify Boss is properly installed: boss --version
  • Try clearing Boss cache: boss cache clean
  • Manually download and install if Boss continues to fail
Solution:
  • Change the port in THorse.Listen(port)
  • Check if another application is using the port
  • Windows: netstat -ano | findstr :9000
  • Linux: netstat -tlnp | grep :9000
Solution:
  • Horse requires OpenSSL DLLs for SSL support
  • Download OpenSSL binaries for your platform
  • Place libeay32.dll and ssleay32.dll in your application directory (Windows)
  • Install OpenSSL package on Linux: apt-get install libssl-dev

​
Next Steps

Quick Start

Build your first Horse application

Routing

Learn about routing and parameters

Middleware

Extend Horse with middleware

Examples

Explore example projects

​
Getting Help

If you encounter issues:
For production deployments, consider using middleware like horse-exception for error handling and horse-logger for request logging.

Build docs developers (and LLMs) love

Get started for freeTalk to us