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).

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: 7.4 or higher (tested up to 8.4). PHP 8.3 or 8.4 recommended — 7.4 and 8.0 still run, but have reached end of life upstream and no longer receive security updates
  • Database: MySQL 8.0 or higher (included with WAMP/XAMPP)
  • Extensions: PHP pdo, pdo_mysql, curl, openssl, mbstring
  • Optional extensions: 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

Technology Stack

Component Technology
Backend PHP 7.4–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