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

Need the full list? See System Requirements.

Choose Your Environment

Already have a development environment? Skip to Step 1.

Need an environment? We recommend these Docker-based options:

For detailed Docker installation, see the Installation Guide.

Step 1: Create Project

Time: 3-5 minutes

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

Time: 1 minute

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;"

Security note: Replace secure_password with a strong, unique password for production environments.

Step 3: Run Installation

Time: 5-10 minutes

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=Admin \
  --admin-lastname=User \
  --admin-email=admin@example.com \
  --admin-user=admin \
  --admin-password=Admin123! \
  --language=en_US \
  --currency=USD \
  --timezone=America/New_York \
  --use-rewrites=1 \
  --search-engine=opensearch \
  --opensearch-host=localhost \
  --opensearch-port=9200

Customize these values:

Step 4: Set Permissions and Deploy

Time: 5-10 minutes

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

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

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: admin (or your custom value)
• Password: Admin123! (or your custom value)

Success! Your Store is Live

Congratulations! You now have a working Mage-OS installation. Here is what to do next:

Essential Configuration

Access Admin > Stores > Configuration to configure:

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

Blank Page After Installation

Cause: Usually a cache or compilation issue.

rm -rf var/cache/* var/page_cache/* generated/*
bin/magento setup:upgrade
bin/magento cache:flush

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.

Composer Memory Limit Errors

Cause: PHP memory limit too low for Composer.

php -d memory_limit=1G /usr/local/bin/composer create-project ...

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.

@TODO: Suggest disable-2fa module for dev instead

Disable 2FA temporarily for development:

bin/magento module:disable Magento_AdminAdobeImsTwoFactorAuth Magento_TwoFactorAuth
bin/magento cache:flush

Static Content Not Loading (CSS/JS Missing)

Cause: Static content not deployed or permissions issue.

bin/magento setup:static-content:deploy -f
bin/magento cache:clean

Next Steps

Now that your store is running, explore these resources:

Join the Community

• Discord: Get real-time help from the community
• GitHub: Report issues and contribute code
• Forums: Discuss best practices and solutions

Visit mage-os.org/community to get connected.