Quick Start Guide
Get from zero to a working Mage-OS store in under 30 minutes. This guide is designed for developers, merchants evaluating the platform, or anyone wanting a fast local development environment.
Total time: 20-30 minutes | Difficulty: Beginner-friendly
Before You Begin
System Requirements
| Component | Version Required |
|---|---|
| PHP | 8.3 or 8.4 |
| Composer | 2.8+ |
| MySQL | 8.4+ (or MariaDB 11.4+) |
| OpenSearch | 2.19+ |
| Web Server | Apache 2.4+ or Nginx 1.26+ |
Need the full list? See System Requirements.
Choose Your Environment
Already have a development environment? Skip to Installation Steps.
Need an environment? We recommend these Docker-based options:
| Tool | Best For | Setup Time |
|---|---|---|
| DDEV | Easiest setup, great for beginners | 5 minutes |
| docker-magento | Production-like, excellent docs | 10 minutes |
| Warden | Production-like, built for managing multiple environments | 10 minutes |
For detailed Docker installation, see the Installation Guide.
Installation Steps
Follow these six steps to get your Mage-OS store up and running
Step 1: Create Project 3-5 min
Use Composer to download Mage-OS and all dependencies into your project directory.
Step 2: Create Database 1 min
Set up a MySQL or MariaDB database and user for your installation.
Step 3: Run Installation 5-10 min
Execute the setup installer to configure your store, admin account, and services.
Step 4: Set Permissions & Deploy 5-10 min
Configure file permissions, compile dependency injection, and deploy static assets.
Step 5: Set Deploy Mode 1 min
Choose developer mode for local work or production mode for live stores.
Step 6: Access Your Store Done!
Open your storefront and admin panel to verify everything is working.
Step 1: Create Project 3-5 min
Navigate to your web server's document root and create a new project:
composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition .What this does:
- Downloads Mage-OS Distribution and all dependencies
- Sets up the basic file structure
- Configures Composer autoloading
Step 2: Create Database 1 min
Create an empty database for your Mage-OS installation:
mysql -u root -p -e "CREATE DATABASE mage_os;"
mysql -u root -p -e "CREATE USER 'mage_os_user'@'localhost' IDENTIFIED BY 'secure_password';"
mysql -u root -p -e "GRANT ALL PRIVILEGES ON mage_os.* TO 'mage_os_user'@'localhost';"
mysql -u root -p -e "FLUSH PRIVILEGES;"Step 3: Run Installation 5-10 min
Run the setup installer with your configuration:
bin/magento setup:install \
--base-url=http://yourdomain.local/ \
--db-host=localhost \
--db-name=mage_os \
--db-user=mage_os_user \
--db-password=secure_password \
--admin-firstname=<your-firstname> \
--admin-lastname=<your-lastname> \
--admin-email=<your-email@example.com> \
--admin-user=<your-username> \
--admin-password=<your-secure-password> \
--language=en_US \
--currency=USD \
--timezone=America/New_York \
--use-rewrites=1 \
--search-engine=opensearch \
--opensearch-host=localhost \
--opensearch-port=9200Customize these values:
| Parameter | Description | Example |
|---|---|---|
--base-url | Your store URL | http://mystore.local/ |
--db-name | Database name | mage_os |
--db-user | Database username | mage_os_user |
--db-password | Database password | Your secure password |
--admin-email | Admin email address | you@example.com |
--admin-user | Admin login username | admin |
--admin-password | Admin login password | Min 7 chars, 1 letter, 1 number |
Step 4: Set Permissions and Deploy 5-10 min
After installation completes, set permissions and deploy assets:
# Set file permissions
find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +
find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +
chmod u+x bin/magento
# Compile dependency injection
bin/magento setup:di:compile
# Deploy static content
bin/magento setup:static-content:deploy -f
# Flush cache
bin/magento cache:flushStep 5: Set Deploy Mode 1 min
For local development:
bin/magento deploy:mode:set developerDeveloper mode provides detailed error messages and disables static file caching for easier debugging.
For production:
bin/magento deploy:mode:set productionProduction mode enables full caching and optimizations for performance.
Step 6: Access Your Store Done!
Storefront
Open your browser and navigate to:
http://yourdomain.local/You should see the default Mage-OS/Magento storefront with the Luma theme.
Admin Panel
Navigate to:
http://yourdomain.local/adminLogin with:
- Username: The value you specified for
--admin-user - Password: The value you specified for
--admin-password
Success! Your Store is Live
Congratulations! You now have a working Mage-OS installation.
Essential Configuration
Access Admin > Stores > Configuration to configure:
| Setting | Location | Purpose |
|---|---|---|
| Store Information | General > General | Store name, address, contact |
| Base URLs | General > Web | Secure URLs for production |
| Payment Methods | Sales > Payment Methods | Enable payment gateways |
| Shipping Methods | Sales > Shipping Methods | Configure shipping options |
| Tax Rules | Sales > Tax | Set up tax calculations |
Set Up Cron Jobs
Mage-OS requires cron for scheduled tasks (indexing, emails, etc.). Use the built-in command to configure cron automatically:
bin/magento cron:installVerify the installation:
bin/magento cron:statusTroubleshooting
Next Steps
Now that your store is running, explore these resources:
Join the Community
Get help, share ideas, and connect with other Mage-OS developers and merchants.
