Get Started

Installation Guide

Comprehensive installation guide for Mage-OS covering all deployment methods. For a quick setup, see the Quick Start Guide.

Overview

Choose Your Installation Method

Select the method that best fits your environment and expertise

Composer

Production servers, VPS, dedicated hosting. Intermediate difficulty, 30-45 minutes.

Docker

Local development, quick testing, reproducible environments. Easy to Intermediate, 15-30 minutes.

Cloud

AWS, GCP, Azure scalable production deployments. Advanced, 1-2 hours.

Composer Installation

Recommended for production installations and custom server environments

1 Create Project

composer create-project --repository-url=https://repo.mage-os.org/ \
  mage-os/project-community-edition <install-directory>

Replace <install-directory> with your desired path or . for current directory.

2 Set File Permissions

cd <install-directory>
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 {} +
chown -R :www-data .
chmod u+x bin/magento

3 Create Database

mysql -u root -p

CREATE DATABASE mageos;
CREATE USER 'mageos'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL ON mageos.* TO 'mageos'@'localhost';
FLUSH PRIVILEGES;
EXIT;

4 Run Installer

bin/magento setup:install \
  --base-url="http://your-domain.com/" \
  --db-host="localhost" \
  --db-name="mageos" \
  --db-user="mageos" \
  --db-password="your_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" \
  --opensearch-index-prefix="mageos" \
  --opensearch-timeout="15"

5 Post-Installation

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento indexer:reindex
bin/magento cache:flush

Docker Installation

Ideal for local development and testing with consistent, reproducible environments

Docker-based environments provide consistent, reproducible setups without modifying your host system. Choose one of these recommended options:

DDEV

Recommended

Easiest setup, great for beginners

5 minutes

ddev.com

docker-magento

Supported

Production-like, excellent docs

10 minutes

GitHub

Warden

Supported

Multi-environment management

10 minutes

warden.dev

Using DDEV Recommended

DDEV is the easiest way to get started with Mage-OS development. It handles all service configuration automatically.

# Install DDEV
curl -fsSL https://ddev.com/install.sh | bash

# Create project directory
mkdir mageos && cd mageos

# Configure DDEV
ddev config --project-type=magento2 --docroot=pub --php-version=8.3

# Start environment
ddev start

# Create Mage-OS project
ddev composer create-project --repository-url=https://repo.mage-os.org/ \
  mage-os/project-community-edition .

# Run installer
ddev magento setup:install \
  --base-url="https://mageos.ddev.site/" \
  --db-host="db" \
  --db-name="db" \
  --db-user="db" \
  --db-password="db" \
  --admin-firstname="<your-firstname>" \
  --admin-lastname="<your-lastname>" \
  --admin-email="<your-email@example.com>" \
  --admin-user="<your-username>" \
  --admin-password="<your-secure-password>" \
  --search-engine="opensearch" \
  --opensearch-host="opensearch" \
  --opensearch-port="9200"

# Deploy
ddev magento setup:di:compile
ddev magento setup:static-content:deploy -f
ddev magento cache:flush

Access your store: https://mageos.ddev.site/

Using docker-magento

docker-magento by Mark Shust is a production-like Docker environment with excellent documentation.

# Download the setup script
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/onelinesetup | bash -s -- mageos.test

# Navigate to project directory
cd mageos.test

# Install Mage-OS (instead of default Magento)
bin/removeall
bin/download --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition

# Start containers and install
bin/setup mageos.test

# Access admin panel
bin/magento admin:user:create \
  --admin-user="<your-username>" \
  --admin-password="<your-secure-password>" \
  --admin-email="<your-email@example.com>" \
  --admin-firstname="<your-firstname>" \
  --admin-lastname="<your-lastname>"

Access your store: https://mageos.test/

Features:

Production-ready Nginx, PHP-FPM, and Redis configuration
Xdebug integration for debugging
Comprehensive helper scripts (bin/magento, bin/composer, etc.)

Using Warden

Warden is a Docker-based development environment specifically designed for Magento and Mage-OS projects with advanced features for professional development teams.

# Install Warden (macOS)
brew install davidalger/warden/warden

# Initialize Warden (first time only)
warden svc up

# Create project
mkdir mageos && cd mageos
warden env-init mageos magento2

# Start environment
warden env up

# Enter shell and install Mage-OS
warden shell
composer create-project --repository-url=https://repo.mage-os.org/ \
  mage-os/project-community-edition .

# Run installer (inside warden shell)
bin/magento setup:install \
  --base-url="https://app.mageos.test/" \
  --db-host="db" \
  --db-name="magento" \
  --db-user="magento" \
  --db-password="magento" \
  --admin-firstname="<your-firstname>" \
  --admin-lastname="<your-lastname>" \
  --admin-email="<your-email@example.com>" \
  --admin-user="<your-username>" \
  --admin-password="<your-secure-password>" \
  --search-engine="opensearch" \
  --opensearch-host="opensearch" \
  --opensearch-port="9200"

# Deploy static content
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Access your store: https://app.mageos.test/

Cloud Deployment

Scalable infrastructure for production Mage-OS deployments

AWS EC2 t3.large minimum

Recommended instance: t3.large (minimum) or t3.xlarge for production

# Connect to your EC2 instance
ssh -i your-key.pem ec2-user@your-instance-ip

# Update system packages
sudo yum update -y

# Install required packages (Amazon Linux 2023)
sudo dnf install -y php8.3 php8.3-{bcmath,cli,common,curl,fpm,gd,intl,mbstring,mysqlnd,opcache,soap,sodium,xml,zip}
sudo dnf install -y nginx mariadb105-server composer
sudo dnf install -y opensearch

# Start services
sudo systemctl enable --now nginx mariadb opensearch php-fpm

# Create database
sudo mysql -e "CREATE DATABASE mageos; CREATE USER 'mageos'@'localhost' IDENTIFIED BY 'your_password'; GRANT ALL ON mageos.* TO 'mageos'@'localhost'; FLUSH PRIVILEGES;"

# Install Mage-OS (in /var/www/mageos)
cd /var/www
sudo composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition mageos
sudo chown -R nginx:nginx mageos

# Follow Composer installation steps 4-5 above

Security group rules:

Port 80 (HTTP) - 0.0.0.0/0
Port 443 (HTTPS) - 0.0.0.0/0
Port 22 (SSH) - Your IP only

Google Cloud Platform n2-standard-2 minimum

Recommended instance: n2-standard-2 (minimum) or n2-standard-4 for production

# Connect via gcloud
gcloud compute ssh your-instance-name

# Update and install packages (Debian/Ubuntu)
sudo apt update && sudo apt upgrade -y
sudo apt install -y php8.3 php8.3-{bcmath,cli,common,curl,fpm,gd,intl,mbstring,mysql,opcache,soap,xml,zip}
sudo apt install -y nginx mysql-server composer

# Install OpenSearch (follow OpenSearch documentation)
# https://opensearch.org/docs/latest/install-and-configure/install-opensearch/debian/

# Start services
sudo systemctl enable --now nginx mysql php8.3-fpm

# Create database
sudo mysql -e "CREATE DATABASE mageos; CREATE USER 'mageos'@'localhost' IDENTIFIED BY 'your_password'; GRANT ALL ON mageos.* TO 'mageos'@'localhost'; FLUSH PRIVILEGES;"

# Install Mage-OS
cd /var/www
sudo composer create-project --repository-url=https://repo.mage-os.org/ mage-os/project-community-edition mageos
sudo chown -R www-data:www-data mageos

# Follow Composer installation steps 4-5 above

Firewall rules:

Allow HTTP (tcp:80)
Allow HTTPS (tcp:443)

Microsoft Azure Standard_D2s_v3 minimum

Recommended VM: Standard_D2s_v3 (minimum) or Standard_D4s_v3 for production

# Connect via Azure CLI
az ssh vm -n your-vm-name -g your-resource-group

# Update and install packages (Ubuntu)
sudo apt update && sudo apt upgrade -y
sudo apt install -y php8.3 php8.3-{bcmath,cli,common,curl,fpm,gd,intl,mbstring,mysql,opcache,soap,xml,zip}
sudo apt install -y nginx mysql-server composer

# Follow same steps as GCP above

Network security group rules:

Allow inbound TCP 80, 443 from Any

Web Server Configuration

Configure Apache or Nginx for Mage-OS

Apache Virtual Host

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /var/www/mageos/pub

    <Directory /var/www/mageos/pub>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/mageos-error.log
    CustomLog ${APACHE_LOG_DIR}/mageos-access.log combined
</VirtualHost>

Nginx Configuration

upstream fastcgi_backend {
    server unix:/var/run/php/php8.3-fpm.sock;
}

server {
    listen 80;
    server_name your-domain.com;

    set $MAGE_ROOT /var/www/mageos;
    set $MAGE_MODE production;

    include /var/www/mageos/nginx.conf.sample;
}

Configuration

Post-Installation Setup

Configure essential settings for optimal performance

Configure Cron Jobs

Required for scheduled tasks like indexing, email sending, and cache management.

# Install cron jobs
bin/magento cron:install

# Verify cron status
bin/magento cron:status

Set Production Mode

Enable production mode for best performance on live stores.

bin/magento deploy:mode:set production

Modes: default (initial), developer (debugging), production (optimized)

Enable Caches

Ensure all caches are enabled for optimal performance.

bin/magento cache:enable
bin/magento cache:status

Install Sample Data

(Optional)

For testing or demonstration purposes.

bin/magento sampledata:deploy
bin/magento setup:upgrade
bin/magento cache:flush

Configure Redis

Recommended

Redis significantly improves cache and session performance. Install Redis first, then configure in app/etc/env.php:

Install Redis

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl enable --now redis-server

# Verify Redis is running
redis-cli ping
# Should return: PONG

Configure env.php

'cache' => [
    'frontend' => [
        'default' => [
            'backend' => 'Magento\Framework\Cache\Backend\Redis',
            'backend_options' => [
                'server' => '127.0.0.1',
                'port' => '6379',
                'database' => '0'
            ]
        ]
    ]
]

Troubleshooting

Solutions for common installation issues

Static content deployment fails

# Use parallel jobs and force mode
bin/magento setup:static-content:deploy -f --jobs=4

# For specific locales
bin/magento setup:static-content:deploy -f en_US en_GB --jobs=4

OpenSearch/Elasticsearch connection failed

# Check if OpenSearch is running
curl http://localhost:9200

# Check service status
sudo systemctl status opensearch

# Restart if needed
sudo systemctl restart opensearch

Clear all caches and regenerate

Nuclear option for persistent issues:

rm -rf var/cache/* var/page_cache/* var/view_preprocessed/* generated/*
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Next Steps

Continue your Mage-OS journey

System Requirements

Verify your setup meets all requirements

View Requirements

Migration Guide

Migrate from Magento Open Source

Start Migration

Quick Start Guide

Quick setup overview

Quick Start

Developer Docs

Full developer documentation

Read DevDocs