Installation - edmozley/freeitsm GitHub Wiki

Installation

There are two supported installation paths: Docker (recommended for quick evaluation) and manual (for production with WAMP/XAMPP/LAMP).

Docker (Recommended)

The fastest way to get FreeITSM running β€” no PHP, MySQL, or web server setup required.

git clone https://github.com/edmozley/freeitsm.git
cd freeitsm
docker compose up -d

Then open http://localhost:8080/setup/ to verify the installation and create your admin account.

Requires Docker Desktop (Windows/Mac) or Docker Engine (Linux).

What the image includes. Since 4.0.0 the image has every PHP extension FreeITSM uses: ldap (LDAP / Active Directory), zip (LMS course upload, Word files in the RFP Builder, searching inside .docx and .xlsx) and intl (international domain names), on top of the ones PHP builds in. Before 4.0.0 it had none of the three (#207), so if you built your own image to add ldap, you can go back to the official one. The build refuses to finish if any of them fails to load.

The one it does not include is imap, so Basic IMAP mailboxes do not work in the container - Microsoft 365 and Gmail mailboxes are not affected. See Basic IMAP mailboxes for why.

Manual Installation

Prerequisites

  • Web server: Apache (WAMP, XAMPP, LAMP) works out of the box. nginx is supported but needs a config file β€” the security rules Apache picks up from .htaccess do not exist on nginx until you install it. See Running on nginx before going live. Apache with PHP-FPM works too. Up to 3.1.0 an uploaded logo and LMS courses did not load on it (why); after updating, run System β†’ Verify database
  • PHP: 8.1 or higher (tested up to 8.4). PHP 8.3 or 8.4 recommended. From 4.0.0 an older PHP gets a page saying so, rather than errors - see Upgrading PHP
  • Database: MySQL 8.0 or higher (included with WAMP/XAMPP)
  • Extensions: PHP pdo, pdo_mysql, curl, openssl, mbstring
  • Optional extensions - each is needed only for the features after it, and the setup page reports which you have:
    • ldap - LDAP / Active Directory sign-in and directory sync
    • zip - LMS course upload (SCORM), Word files in the RFP Builder, searching inside .docx and .xlsx attachments
    • intl - international domain names (such as mΓΌnchen.de) in Domains
    • imap - only needed for basic IMAP/SMTP mailboxes. Note that PHP 8.4 no longer bundles imap; on 8.4 you must install it from PECL, or that mailbox type will silently collect no mail. The setup page reports whether it's present
  • Database credentials file: A db_config.php file stored outside your web root (e.g. C:\wamp64\db_config.php) β€” the path is configured in config.php (see step 2 below)

⚠️ Note for early adopters: If you downloaded FreeITSM before 18 February 2026, the project required Microsoft SQL Server Express and ODBC drivers. FreeITSM now runs on MySQL with no extra drivers needed. Existing SQL Server installs will need a data migration, plus an update to db_config.php for MySQL.

Steps

  1. Clone the repository

    git clone https://github.com/edmozley/freeitsm.git
cd freeitsm

  2. Configure database credentials Copy db_config.sample.php to a secure location outside your web root:

    C:\wamp64\db_config.php  (recommended on Windows)

    Edit the copied file with your MySQL credentials:

    define('DB_SERVER', 'localhost');
define('DB_NAME', 'freeitsm');
define('DB_USERNAME', 'your_username');
define('DB_PASSWORD', 'your_password');

    Update config.php line 10 if you chose a different location.

  3. Create the database Create a database named freeitsm in MySQL. Run database/freeitsm.sql to create all tables, or use the Setup page's DB Verify to auto-create them.

  4. Set up encryption key (for sensitive settings)

    mkdir C:\wamp64\encryption_keys
# Generate a random 256-bit key (64 hex characters)
php -r "echo bin2hex(random_bytes(32));" > C:\wamp64\encryption_keys\sdtickets.key

    The key file defaults to C:\wamp64\encryption_keys\sdtickets.key (Windows) or /var/www/encryption_keys/freeitsm.key (Linux). To keep it elsewhere β€” e.g. your web root isn't /var/www β€” set its path in config.php (define('ENCRYPTION_KEY_PATH', '/your/path/...')) or via the ENCRYPTION_KEY_PATH environment variable (used by the Docker image).

  5. Configure web server

    • Point your web server to the application root
    • Ensure PHP extensions are enabled: pdo_mysql, curl, openssl, mbstring
    • Restart your web server

  6. Verify setup Navigate to http://your-server/setup/ to run the verification checks (config files, database connection, PHP extensions, security settings). Delete the /setup folder once your system is in production.

  7. First login Navigate to http://your-server/login.php. A default admin account is created by the SQL script:

    • Username: admin
    • Password: freeitsm

    Change this password immediately after first login via the account menu.

  8. Import demo data (optional) Navigate to System β†’ Demo Data to populate modules with realistic sample data. Import Core first (creates analysts, departments, teams, end users), then choose which modules to populate.

    • Includes tickets, assets, knowledge articles, changes, calendar events, morning checks, contracts, service status, software licences, forms, tasks, process flowcharts, and CMDB objects
    • Demo analysts use password demo1234
    • Designed for fresh installations only β€” each module can be imported once

Configuration Files

File Location Purpose Commit to Git?
config.php Web root Main config (references external DB config) βœ… Yes
db_config.php Outside web root Database credentials ❌ No
db_config.sample.php Web root Template for db_config.php βœ… Yes
sdtickets.key Outside web root AES-256-GCM encryption key ❌ No

Showing PHP errors on a development box

FreeITSM always logs PHP errors and never shows them in a web page, because a warning printed into a page names server paths - and before sign-in that is shown to anybody. Scripts run from the command line (cron, tests) always show them.

To see them in the browser while developing, add this to db_config.php - not config.php, which is replaced every time you pull an upgrade:

define('FREEITSM_DISPLAY_ERRORS', true);

In Docker, set FREEITSM_DISPLAY_ERRORS=1 in the app's environment: in docker-compose.yml instead (errors also go to docker logs either way). Never turn it on for an install people use.

Technology Stack

Component Technology
Backend PHP 8.1–8.4
Database MySQL 8.0+ (PDO MySQL)
Frontend Vanilla JavaScript, HTML5, CSS3 (no frameworks)
Rich Text Editor TinyMCE 6+
Email integration Microsoft Graph API + Gmail API (OAuth 2.0)
Encryption AES-256-GCM (sensitive data at rest)
Web server Apache (WAMP/XAMPP/LAMP), or nginx with its config file