Installation

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
• 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