Getting Started

This guide walks you through setting up a fresh Maho installation. Maho supports both CLI and web-based installation workflows, multi-database engines (MySQL, PostgreSQL, SQLite), and optional sample data import.

Prerequisites

Before installing Maho, ensure your environment meets these requirements:

Server Requirements:

• PHP 8.3 or higher
• Web server (Apache, Nginx, or built-in PHP server)
• One of: MySQL 8.0+, PostgreSQL 13+, or SQLite 3.x
• Composer for dependency management

Required PHP Extensions: Maho requires several PHP extensions to be loaded for core functionality, as checked by the installer configuration:

• ctype, curl, dom, fileinfo, filter, ftp, gd, hash, iconv, intl, json, libxml, mbstring, pdo, session, simplexml, soap, spl, zlib
• One of: pdo_mysql, pdo_pgsql, pdo_sqlite
• One of: openssl or mcrypt (for encryption)

Filesystem Permissions: The web server must have write access to specific paths defined in the installation configuration:

• app/etc/ - for configuration files (specifically local.xml)
• var/ - for cache, sessions, logs, and SQLite databases
• media/ - for uploaded media files

Sources: app/code/core/Mage/Install/etc/install.xml48-97 app/code/core/Mage/Install/Model/Installer/Config.php83-91

Installation Methods

Maho provides two installation methods that produce identical results:

Method	Command/URL	Use Case
CLI	./maho install	Automated deployments, scripting, headless environments
Web Wizard	http://yoursite.com/install	First-time installations, visual feedback, guided setup

Both methods create:

• app/etc/local.xml using a template to store database credentials and a generated encryption key app/code/core/Mage/Install/Model/Installer/Config.php78-93
• Complete database schema via module migration scripts managed by Mage_Core_Model_Resource_Setup app/code/core/Mage/Core/Model/Resource/Setup.php196-226
• Admin user account with specified credentials
• Initial system configuration

Sources: lib/MahoCLI/Commands/Install.php26-30 app/code/core/Mage/Install/controllers/WizardController.php13-26

Installation Overview

The installation process follows a structured sequence of steps regardless of the interface used.

High-Level Installation Flow

Sources: app/code/core/Mage/Install/etc/install.xml14-46 lib/MahoCLI/Commands/Install.php78-125 app/code/core/Mage/Core/Model/Resource/Setup.php196-226

CLI Installation Quick Start

The ./maho install command, implemented in MahoCLI\Commands\Install, provides a scriptable installation method.

Key Options:

• --db_engine: Choose mysql, pgsql, or sqlite lib/MahoCLI/Commands/Install.php49
• --sample_data: Automatically downloads and imports demo content lib/MahoCLI/Commands/Install.php71
• --force: Clears existing installation by dropping the database and removing local.xml lib/MahoCLI/Commands/Install.php74

For complete CLI installation documentation, see Installation.

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

Web Wizard Quick Start

Navigate to http://yoursite.com/install to launch the installation wizard. The wizard guides you through steps defined in Mage_Install_WizardController:

Web Wizard Steps

Wizard Implementation

Step	Controller Action	Purpose
License	licenseAction()	Accept OSL 3.0 license agreement app/code/core/Mage/Install/controllers/WizardController.php64-79
Localization	localeAction()	Select locale, timezone, currency; optional language pack installation app/code/core/Mage/Install/controllers/WizardController.php93-106
Database	configurationAction()	Configure database connection and basic URLs app/code/core/Mage/Install/controllers/WizardController.php141-160
Sample Data	sampledataAction()	Optionally install demo products and content via Mage_Install_Model_Installer_SampleData app/code/core/Mage/Install/Model/Installer/SampleData.php107-145
Admin User	administratorAction()	Create initial admin account
Complete	completeAction()	Display success and access links app/code/core/Mage/Install/Block/Complete.php15-27

The wizard automatically handles:

• Database schema creation via installDbAction() app/code/core/Mage/Install/controllers/WizardController.php192-211
• Sample data orchestration including progress tracking app/code/core/Mage/Install/Model/Installer/SampleData.php107-145

For detailed web installation documentation, see Installation.

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

Database Engine Support

Maho supports three database engines. The Mage_Install_Model_Installer_Config class manages the generation of the connection configuration in local.xml app/code/core/Mage/Install/Model/Installer/Config.php13-29

Engine	Configuration	Storage	Notes
MySQL	mysql	Remote server	Default choice, uses Maho\Db\Adapter\Pdo\Mysql app/etc/config.xml64
PostgreSQL	pgsql	Remote server	Uses Maho\Db\Adapter\Pdo\Pgsql app/etc/config.xml68
SQLite	sqlite	var/db/{name}	Uses Maho\Db\Adapter\Pdo\Sqlite app/etc/config.xml72

Database Setup Flow

Migration scripts follow the naming convention sql/{module}_setup/maho-{version}.php. For example, a recent catalog migration adds specific product attributes to the EAV system app/code/core/Mage/Catalog/sql/maho_setup/maho-26.1.0.php17-49

Sources: lib/MahoCLI/Commands/Install.php44-49 app/code/core/Mage/Catalog/sql/maho_setup/maho-26.1.0.php1-52 app/etc/config.xml60-77

Sample Data (Optional)

Sample data provides demo content to explore Maho features. It is managed by Mage_Install_Model_Installer_SampleData, which handles the lifecycle from download to reindexing app/code/core/Mage/Install/Model/Installer/SampleData.php107-145

Sample Data Architecture

The SampleDataImporter performs sophisticated EAV attribute ID remapping to handle differences between sample data's hardcoded IDs and the fresh installation's actual IDs lib/MahoCLI/Helper/SampleDataImporter.php18-24

For detailed sample data import documentation, see Sample Data Import.

Sources: lib/MahoCLI/Commands/Install.php128-158 app/code/core/Mage/Install/Model/Installer/SampleData.php106-145 lib/MahoCLI/Helper/SampleDataImporter.php18-128

Post-Installation State

After installation completes, the following components are initialized:

Configuration and Filesystem

• app/etc/local.xml: Contains the crypt/key and resources/db settings app/code/core/Mage/Install/Model/Installer/Config.php78-93
• var/ subdirectories: cache, session, and log are used for runtime data.

Database and Access

• Schema: All tables for core and active modules are created.
• Admin User: A user is created in the admin_user table.
• Storefront: Accessible at the base URL; the admin panel is at the configured admin_frontname lib/MahoCLI/Commands/Install.php55-56

Next Steps

1. Access the storefront: Visit your base URL.
2. Access the admin panel: Visit the /admin path (or your custom path).
3. Review configuration: Use the Admin UI or CLI to verify settings.
4. Set up cron: Maho relies on cron for tasks like indexing and email.

For more detailed information:

• Configuration system: See Configuration System Overview
• Module system: See Module System
• CLI development: See CLI Architecture

Sources: lib/MahoCLI/Commands/Install.php99-125 app/code/core/Mage/Install/controllers/WizardController.php192-211