Installation

This page documents the installation process for Maho, covering both CLI and web-based installation methods, system requirements, database configuration, and sample data import. For ongoing configuration management after installation, see Configuration System. For development environment setup, see Development Environment Setup.

Purpose and Scope

This documentation covers:

• Installation methods (CLI command and web wizard)
• System requirements and dependency management
• Multi-database engine support (MySQL, PostgreSQL, SQLite)
• Sample data import with EAV attribute remapping
• Configuration file generation and encryption key setup

---

Installation Methods Overview

Maho provides two installation paths: CLI via MahoCLI\Commands\Install and a web-based wizard via Mage_Install_WizardController. Both methods utilize the underlying Mage_Install_Model_Installer to perform the actual setup.

Installation Methods Comparison

Sources: lib/MahoCLI/Commands/Install.php78-115 app/code/core/Mage/Install/etc/install.xml14-47 app/code/core/Mage/Install/controllers/WizardController.php13-25

---

System Requirements

PHP Requirements

Maho requires PHP 8.3 or higher. The installation wizard and CLI check for the presence of essential extensions defined in install.xml.

Extension	Purpose	Required
ctype	Character type checking	✓
curl	HTTP client operations	✓
dom	XML DOM manipulation	✓
fileinfo	File type detection	✓
gd	Image processing	✓
intl	Internationalization	✓
json	JSON encoding/decoding	✓
mbstring	Multibyte string handling	✓
openssl	Encryption and SSL	✓
pdo_mysql	MySQL database driver	✓
pdo_pgsql	PostgreSQL support	Optional
pdo_sqlite	SQLite support	Optional

Sources: app/code/core/Mage/Install/etc/install.xml68-96 app/locale/en_US/Mage_Install.csv74-83

---

CLI Installation

The CLI installation is handled by the install command, implemented in the MahoCLI\Commands\Install class. It allows for non-interactive setup which is ideal for CI/CD pipelines.

Installation Options

The Install command accepts the following primary options:

Option	Description
--db_host	Database server host (supports port or UNIX socket) lib/MahoCLI/Commands/Install.php44
--db_name	Database name lib/MahoCLI/Commands/Install.php45
--db_engine	Database engine: mysql, pgsql, or sqlite (default: mysql) lib/MahoCLI/Commands/Install.php49
--url	Base URL for the store (must end with /) lib/MahoCLI/Commands/Install.php56
--sample_data	Flag to trigger sample data download and import lib/MahoCLI/Commands/Install.php71
--force	Drops existing database and removes local.xml before starting lib/MahoCLI/Commands/Install.php74

Sources: lib/MahoCLI/Commands/Install.php33-75

Force Installation Process

When the --force flag is used, Maho cleans the environment to ensure a fresh state. The handleForceInstall method manages this cleanup.

Sources: lib/MahoCLI/Commands/Install.php81-85 app/code/core/Mage/Install/Model/Installer/Config.php28

---

Web Installation Wizard

The web wizard is a stateful multi-step process managed by Mage_Install_WizardController. It uses Mage_Install_Model_Session to store intermediate data before writing the final configuration.

Wizard Steps

The steps are defined in install.xml and correspond to actions in the controller:

1. License: Agreement to OSL 3.0 app/code/core/Mage/Install/etc/install.xml16-20
2. Locale: Selection of language, timezone, and currency app/code/core/Mage/Install/etc/install.xml21-25
3. Configuration: Database credentials and Web access options app/code/core/Mage/Install/etc/install.xml26-30
4. Sample Data: Optional step to populate the store with demo products app/code/core/Mage/Install/etc/install.xml31-35
5. Administrator: Creation of the first admin user app/code/core/Mage/Install/etc/install.xml36-40
6. Complete: Finalization and cleanup app/code/core/Mage/Install/etc/install.xml41-45

Sources: app/code/core/Mage/Install/etc/install.xml14-47 app/code/core/Mage/Install/controllers/WizardController.php59-208

---

Sample Data Import

Maho features a modernized sample data installer that handles cross-database compatibility and EAV attribute remapping.

EAV Attribute Remapping

Since attribute IDs in the sample data SQL dump might conflict with existing IDs in a fresh Maho installation, the SampleDataImporter remaps them dynamically. It parses the SQL to build a mapping between "old" IDs and "current" IDs based on attribute codes and entity types lib/MahoCLI/Helper/SampleDataImporter.php18-24

Key Remapping Tables: The importer specifically targets tables containing attribute_id or option_id columns:

• catalog_product_entity_* (datetime, decimal, int, text, varchar) lib/MahoCLI/Helper/SampleDataImporter.php52-56
• catalog_category_entity_* lib/MahoCLI/Helper/SampleDataImporter.php47-51
• eav_attribute_option lib/MahoCLI/Helper/SampleDataImporter.php61
• catalog_product_super_attribute lib/MahoCLI/Helper/SampleDataImporter.php63

Sources: lib/MahoCLI/Helper/SampleDataImporter.php46-65 lib/MahoCLI/Helper/SampleDataImporter.php18-24 lib/MahoCLI/Helper/SampleDataImporter.php133-135

Background Processing (Web Wizard)

In the web wizard, sample data installation is performed as an asynchronous-style process managed by Mage_Install_Model_Installer_SampleData. It provides progress tracking via a JSON file app/code/core/Mage/Install/Model/Installer/SampleData.php24

• Model: Mage_Install_Model_Installer_SampleData app/code/core/Mage/Install/Model/Installer/SampleData.php22
• Progress Tracking: Stores status in var/sampledata_progress.json app/code/core/Mage/Install/Model/Installer/SampleData.php36
• Phases: downloading, extracting, copying_media, importing_data, reindexing app/code/core/Mage/Install/Model/Installer/SampleData.php110-128

Sources: app/code/core/Mage/Install/Model/Installer/SampleData.php22-145 app/code/core/Mage/Install/Model/Installer/SampleData.php34-37

---

Database Configuration and local.xml

The result of the installation is the generation of app/etc/local.xml. This file is created from a template by replacing placeholders with user-provided values app/code/core/Mage/Install/Model/Installer/Config.php78-82

Multi-Database Support

Maho uses a database abstraction layer that allows installation on different engines. The SampleDataImporter detects the driver and adjusts schema introspection accordingly.

Engine	Driver Name	Schema Query Method
MySQL	mysql	SHOW COLUMNS FROM lib/MahoCLI/Helper/SampleDataImporter.php188-191
PostgreSQL	pgsql	information_schema.columns lib/MahoCLI/Helper/SampleDataImporter.php192-199
SQLite	sqlite	PRAGMA table_info lib/MahoCLI/Helper/SampleDataImporter.php201-204

Sources: lib/MahoCLI/Helper/SampleDataImporter.php187-204 lib/MahoCLI/Commands/Install.php49 app/etc/config.xml60-77

Config Generation Implementation

The Mage_Install_Model_Installer_Config class handles the writing of the local.xml file. It replaces temporary values for the installation date and encryption key after the initial file creation to ensure security and accurate timestamps app/code/core/Mage/Install/Model/Installer/Config.php166-185

Sources: app/code/core/Mage/Install/Model/Installer/Config.php48-95 app/code/core/Mage/Install/Model/Installer/Config.php166-185

---

Technical Flow: Database Setup

The install() method in the CLI installer triggers the initialization of the Maho environment and the execution of the installation process via Mage_Install_Model_Installer_Console.

Sources: lib/MahoCLI/Commands/Install.php105-110 app/code/core/Mage/Install/Model/Installer/Config.php48-95