Magento 2: Installation Guide

Complete guide for installing Magento 2 (Open Source and Adobe Commerce) on Ubuntu/Debian Linux systems.

Table of Contents

Overview
System Requirements
- Minimum Requirements
- Hardware Recommendations
Prerequisites Installation
Installation Methods
- Method 1: Install via Composer (Recommended)
- Method 2: Install from Archive
Configure Apache Virtual Host
Post-Installation Configuration
Verification
- Check Installation
Performance Optimization
Troubleshooting
- Common Issues
Maintenance Commands
Security Best Practices
Quick Reference
- Essential Commands
- Installation Checklist
See Also

Overview 

This guide covers:

System requirements and prerequisites
Installation via Composer (recommended)
Installation via Archive
Post-installation configuration
Common installation issues and solutions

System Requirements 

Minimum Requirements 

Operating System - Linux x86-64 (Ubuntu 20.04/22.04, Debian 10/11)

Web Server - Apache 2.4.x with mod_rewrite - Nginx 1.x

Database - MySQL 8.0 - MariaDB 10.4, 10.5, 10.6

PHP - PHP 8.1, 8.2, 8.3 (for Magento 2.4.6+) - PHP 8.1, 8.2 (for Magento 2.4.4-2.4.5)

Composer - Composer 2.x

Search Engine - Elasticsearch 7.17, 8.x - OpenSearch 1.x, 2.x

Optional - Redis 6.x or later (for cache and session storage) - Varnish 7.x (for page caching) - RabbitMQ 3.11 (for message queues)

Hardware Recommendations 

Component	Minimum	Recommended
RAM	2 GB	4 GB+
CPU	2 cores	4+ cores
Disk Space	2 GB	10 GB+ (SSD)

Prerequisites Installation 

Before installing Magento 2, you need to have a LAMP stack (Linux, Apache, MySQL, PHP) configured on your system.

For detailed installation instructions, please refer to:

LAMP Stack Installation Guide - Complete LAMP stack installation guide including Apache, MySQL, PHP, Elasticsearch, and Composer installation
Linux: Switch Between Multiple PHP Versions - Guide for switching between multiple PHP versions

Quick Summary 

If you already have LAMP stack installed, ensure you have:

PHP 8.1 or 8.2 (for Magento 2.4.4-2.4.5)
PHP 8.1, 8.2, or 8.3 (for Magento 2.4.6+)
All required PHP extensions (see list below)
Composer 2.x
MySQL 8.0 or MariaDB 10.4+
Elasticsearch 7.17, 8.x or OpenSearch 1.x, 2.x

Required PHP Extensions 

Ensure the following PHP extensions are installed:

bcmath, ctype, curl, dom, fileinfo, gd, hash, iconv, intl,
json, libxml, mbstring, openssl, pcre, pdo_mysql, simplexml,
soap, sodium, spl, xsl, zip, zlib

To check installed extensions:

php -m | grep -E 'bcmath|ctype|curl|dom|fileinfo|gd|hash|iconv|intl|json|libxml|mbstring|openssl|pcre|pdo_mysql|simplexml|soap|sodium|spl|xsl|zip|zlib'

Configure PHP for Magento 

Edit PHP configuration file:

sudo nano /etc/php/8.2/apache2/php.ini

Update the following settings:

memory_limit = 2G
max_execution_time = 1800
zlib.output_compression = On
upload_max_filesize = 64M
post_max_size = 64M

Restart Apache:

sudo systemctl restart apache2

Create Database 

Create a database for Magento:

sudo mysql -u root -p

CREATE DATABASE magento2;
CREATE USER 'magento2user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON magento2.* TO 'magento2user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Installation Methods 

Method 1: Install via Composer (Recommended)

Step 1: Get Authentication Keys

Go to https://marketplace.magento.com/
Navigate to My Profile > Marketplace > My Products > Access Keys
Generate new keys or use existing ones - Public Key = Username - Private Key = Password

Step 2: Create Project Directory

cd /var/www/html
sudo mkdir magento2
sudo chown -R $USER:$USER magento2
cd magento2

Step 3: Install Magento

# For Magento Open Source
composer create-project --repository-url=https://repo.magento.com/ magento/project-community-edition .

# For Adobe Commerce
composer create-project --repository-url=https://repo.magento.com/ magento/project-enterprise-edition .

When prompted, enter your authentication keys.

Step 4: Set Permissions

cd /var/www/html/magento2
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

Step 5: Run Installation

php bin/magento setup:install \
--base-url=http://magento2.local/ \
--db-host=localhost \
--db-name=magento2 \
--db-user=magento2user \
--db-password=strong_password \
--admin-firstname=Admin \
--admin-lastname=User \
--admin-email=admin@example.com \
--admin-user=admin \
--admin-password=Admin@123 \
--language=en_US \
--currency=USD \
--timezone=America/Chicago \
--use-rewrites=1 \
--search-engine=elasticsearch8 \
--elasticsearch-host=localhost \
--elasticsearch-port=9200 \
--elasticsearch-index-prefix=magento2 \
--elasticsearch-timeout=15

Method 2: Install from Archive 

Step 1: Download Magento

cd /var/www/html
wget https://github.com/magento/magento2/archive/2.4.6.tar.gz
tar -xzvf 2.4.6.tar.gz
mv magento2-2.4.6 magento2

Step 2: Install Dependencies

cd /var/www/html/magento2
composer install

Step 3: Set Permissions and Install

Follow steps 4-5 from Method 1.

Configure Apache Virtual Host 

For detailed Apache virtual host configuration, refer to:

Apache Virtual Host Configuration Guide - Complete guide for creating and configuring Apache virtual hosts

Create Virtual Host Configuration 

Create a virtual host configuration for your Magento installation:

sudo nano /etc/apache2/sites-available/magento2.conf

Add the following configuration:

<VirtualHost *:80>
    ServerName magento2.local
    ServerAdmin admin@example.com
    DocumentRoot /var/www/html/magento2/pub

    <Directory /var/www/html/magento2/pub>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/magento2_error.log
    CustomLog ${APACHE_LOG_DIR}/magento2_access.log combined
</VirtualHost>

Enable Site and Modules 

# Enable rewrite module
sudo a2enmod rewrite

# Enable site
sudo a2ensite magento2.conf

# Disable default site
sudo a2dissite 000-default.conf

# Restart Apache
sudo systemctl restart apache2

Update Hosts File 

sudo nano /etc/hosts

Add:

127.0.0.1   magento2.local

Post-Installation Configuration 

Common Post-Installation Steps 

After installation, you may need to perform these common steps:

Change admin URL (if needed):

Edit app/etc/env.php to change the admin URL from generated path (e.g., /admin_1ojk54) to admin.
Disable Two-Factor Authentication Module (for local development):
```
php bin/magento module:disable Magento_TwoFactorAuth
```

Run common Magento commands:

php bin/magento deploy:mode:set developer
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento indexer:reindex
php bin/magento cache:clean
php bin/magento cache:flush
sudo chmod -R 777 generated/ pub/ var/

Or use shortcut commands:

php bin/magento deploy:mode:set developer
php bin/magento s:up
php bin/magento s:d:c
php bin/magento s:s:d -f
php bin/magento i:rei
php bin/magento c:c
php bin/magento c:f
sudo chmod -R 777 generated/ pub/ var/

Where:

s:up = setup:upgrade
s:d:c = setup:di:compile
s:s:d -f = setup:static-content:deploy -f
i:rei = indexer:reindex
c:c = cache:clean
c:f = cache:flush

Check your frontend and admin are working properly.

Deploy Static Content 

php bin/magento setup:static-content:deploy -f

Set Magento Mode 

# For development
php bin/magento deploy:mode:set developer

# For production
php bin/magento deploy:mode:set production

Configure Cron 

# Install cron
php bin/magento cron:install

# Verify cron is running
crontab -l

Configure Redis (Optional)

Install Redis

sudo apt install redis-server -y
sudo systemctl enable redis-server
sudo systemctl start redis-server

Configure Magento to use Redis

Edit app/etc/env.php:

'cache' => [
    'frontend' => [
        'default' => [
            'backend' => 'Cm_Cache_Backend_Redis',
            'backend_options' => [
                'server' => '127.0.0.1',
                'port' => '6379',
                'database' => '0',
                'compress_data' => '1'
            ]
        ],
        'page_cache' => [
            'backend' => 'Cm_Cache_Backend_Redis',
            'backend_options' => [
                'server' => '127.0.0.1',
                'port' => '6379',
                'database' => '1',
                'compress_data' => '1'
            ]
        ]
    ]
],

Configure Two-Factor Authentication 

Disable for local development:

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

Verification 

Check Installation 

1. Access Frontend

Open browser: http://magento2.local/

2. Access Admin Panel

URL: http://magento2.local/admin

3. Run System Check

php bin/magento sys:check

4. Check Module Status

php bin/magento module:status

5. Verify Cron

php bin/magento cron:run
tail -f var/log/system.log

Performance Optimization 

Enable Flat Catalog 

# Enable flat catalog
php bin/magento config:set catalog/frontend/flat_catalog_category 1
php bin/magento config:set catalog/frontend/flat_catalog_product 1

# Reindex
php bin/magento indexer:reindex

Configure Full Page Cache 

# Enable full page cache
php bin/magento cache:enable full_page

Production Mode Optimization 

# Compile DI
php bin/magento setup:di:compile

# Deploy static content
php bin/magento setup:static-content:deploy -f

# Set production mode
php bin/magento deploy:mode:set production

Troubleshooting 

Common Issues 

Issue 1: Permission Errors

cd /var/www/html/magento2
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

Issue 2: 404 Error on Admin

php bin/magento cache:flush
php bin/magento setup:upgrade

Issue 3: Blank Pages

Check PHP error logs:

tail -f /var/log/apache2/magento2_error.log
tail -f var/log/system.log
tail -f var/log/exception.log

Enable display errors in pub/index.php:

ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

Issue 4: Elasticsearch Connection Failed

# Check Elasticsearch status
sudo systemctl status elasticsearch

# Test connection
curl -X GET 'http://localhost:9200'

# Restart Elasticsearch
sudo systemctl restart elasticsearch

Issue 5: Composer Authentication

# Clear composer cache
composer clear-cache

# Re-add credentials
composer config --global http-basic.repo.magento.com <public_key> <private_key>

Issue 6: Out of Memory

Increase PHP memory limit:

sudo nano /etc/php/8.2/apache2/php.ini
# Set: memory_limit = 4G

sudo systemctl restart apache2

Maintenance Commands 

Update Magento 

# Enable maintenance mode
php bin/magento maintenance:enable

# Backup
php bin/magento setup:backup --code --media --db

# Update via composer
composer update

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

# Disable maintenance
php bin/magento maintenance:disable

Backup Database 

# Create backup
php bin/magento setup:backup --db

# Manual backup
mysqldump -u magento2user -p magento2 > magento2_backup_$(date +%Y%m%d).sql

Clear Cache 

# Clear all cache
php bin/magento cache:flush

# Clear specific cache
php bin/magento cache:clean config full_page

# Manually clear cache
rm -rf var/cache/* var/page_cache/* var/view_preprocessed/*

Reindex Data 

# Reindex all
php bin/magento indexer:reindex

# Reindex specific indexer
php bin/magento indexer:reindex catalog_product_price

# Check indexer status
php bin/magento indexer:status

Security Best Practices 

Change Admin URL

php bin/magento setup:config:set --backend-frontname="custom_admin"

Use Strong Passwords - Admin password minimum 12 characters - Database password should be complex

Disable Developer Mode in Production

php bin/magento deploy:mode:set production

Enable Two-Factor Authentication

php bin/magento module:enable Magento_TwoFactorAuth

Regular Updates - Keep Magento updated - Update PHP, MySQL, and server software
Set Proper File Permissions - Follow Magento’s permission guidelines - Don’t use 777 permissions
Use HTTPS - Install SSL certificate - Force HTTPS in Magento admin

Quick Reference 

Essential Commands 

Command	Description
`setup:install`	Install Magento
`setup:upgrade`	Update database schema
`setup:di:compile`	Compile dependencies
`setup:static-content:deploy`	Deploy static files
`cache:flush`	Clear cache
`indexer:reindex`	Reindex data
`deploy:mode:set`	Set Magento mode
`maintenance:enable/disable`	Toggle maintenance mode
`cron:install`	Install cron jobs
`module:status`	List module status

Installation Checklist 

☐ System requirements met
☐ Apache/Nginx installed
☐ MySQL/MariaDB installed
☐ PHP 8.x with all extensions
☐ Composer installed
☐ Elasticsearch installed
☐ Database created
☐ Authentication keys obtained
☐ Magento installed
☐ Virtual host configured
☐ Permissions set
☐ Cron configured
☐ Admin accessible
☐ Frontend working