Get Started

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 - 8.5
Composer	2.10.2+
MySQL	8.4+ (or MariaDB 12.3+)
OpenSearch	3+
Web Server	Apache 2.4+ or Nginx 1.28+

Need the full list? See System Requirements.

Choose Your Environment

Already have a development environment? On DDEV or Warden, skip to the Mage-OS Installer. Anywhere else, 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.

Shortcut: Mage-OS Installer 5 min

Automates every step below if you use DDEV or Warden

The Mage-OS Installer detects your local environment and handles the project creation, database, and setup:install steps for you. Services such as OpenSearch, Redis, RabbitMQ, and Varnish are configured out of the box.

1. Install the binary

Apple Silicon:

sudo curl -sL -o /usr/local/bin/mage-os-install https://github.com/mage-os-lab/mage-os-installer/releases/latest/download/mage-os-install_darwin_arm64
sudo chmod +x /usr/local/bin/mage-os-install

Intel:

sudo curl -sL -o /usr/local/bin/mage-os-install https://github.com/mage-os-lab/mage-os-installer/releases/latest/download/mage-os-install_darwin_amd64
sudo chmod +x /usr/local/bin/mage-os-install

x86_64:

sudo curl -sL -o /usr/local/bin/mage-os-install https://github.com/mage-os-lab/mage-os-installer/releases/latest/download/mage-os-install_linux_amd64
sudo chmod +x /usr/local/bin/mage-os-install

ARM64:

sudo curl -sL -o /usr/local/bin/mage-os-install https://github.com/mage-os-lab/mage-os-installer/releases/latest/download/mage-os-install_linux_arm64
sudo chmod +x /usr/local/bin/mage-os-install

Running DDEV or Warden in WSL2? Use the Linux x86_64 command from the Linux tab and run it inside your WSL2 distribution. This is the recommended setup for DDEV and the only supported one for Warden.

For a traditional Windows DDEV install, download mage-os-install_windows_amd64.exe (or mage-os-install_windows_arm64.exe) from the releases page and add the directory to your PATH.

Build from source with Go installed:

go install github.com/mage-os-lab/mage-os-installer@latest

2. Run the installer

Run it from the directory where you want your project:

mage-os-install

It walks you through:

Project name - defaults to the current directory name
Install directory - where to create the project
Environment - DDEV or Warden, auto-selected if only one is available
Admin credentials - the Mage-OS admin user
Command review - inspect the setup:install flags before running
Installation - progress in real time

When it finishes, your store is available at:

Environment	Site URL
DDEV	`https://{project}.test`
Warden	`https://app.{project}.test`

Installation Steps

Follow these six steps to set up your Mage-OS store manually

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 installer with your configuration:

Walks you through every setting interactively - no flags to memorize. Recommended for first-time setups.

bin/magento install

Pass all options as flags in a single command. Useful for scripted or automated deployments.

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=9200

Customize 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:flush

Step 5: Set Deploy Mode 1 min

For local development:

bin/magento deploy:mode:set developer

Developer mode provides detailed error messages and disables static file caching for easier debugging.

For production:

bin/magento deploy:mode:set production

Production 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/admin

Login 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:install

Verify the installation:

bin/magento cron:status

Troubleshooting

404 Errors on Storefront Pages

Cause: Apache mod_rewrite not enabled.

sudo a2enmod rewrite
sudo systemctl restart apache2

For Nginx, ensure your configuration includes the rewrite rules. See the Installation Guide.

OpenSearch Connection Failed

Cause: OpenSearch service not running.

Verify OpenSearch is running:

curl http://localhost:9200

You should see a JSON response with cluster information. If not, start OpenSearch:

sudo systemctl start opensearch

Admin Login Not Working

Cause: Two-factor authentication is enabled by default.

Install the DisableTwoFactorAuth module which automatically disables 2FA in developer mode while keeping it enabled in production:

composer require --dev markshust/magento2-module-disabletwofactorauth
bin/magento module:enable MarkShust_DisableTwoFactorAuth
bin/magento setup:upgrade

Next Steps

Now that your store is running, explore these resources:

Full Installation Guide

Detailed installation instructions for Docker, cloud hosting, and custom environments.

View Guide

Migration Guide

Step-by-step instructions for migrating from Magento Open Source to Mage-OS.

Start Migration

System Requirements

Complete technical specifications for PHP, databases, search engines, and more.

View Requirements

Developer Documentation

Full developer documentation with API references, tutorials, and best practices.

Read DevDocs

Join the Community

Get help, share ideas, and connect with other Mage-OS developers and merchants.

Join Discord

GitHub

Community Hub

Quick Start Guide

Before You Begin

System Requirements

Choose Your Environment

Shortcut: Mage-OS Installer 5 min

1. Install the binary

2. Run the installer

Installation Steps

Step 1: Create Project 3-5 min

Step 2: Create Database 1 min

Step 3: Run Installation 5-10 min

Step 4: Set Permissions and Deploy 5-10 min

Step 5: Set Deploy Mode 1 min

Step 6: Access Your Store Done!

Storefront

Admin Panel

Success! Your Store is Live

Essential Configuration

Set Up Cron Jobs

Troubleshooting

Next Steps

Full Installation Guide

Migration Guide

System Requirements

Developer Documentation

Join the Community

Our Partners