Magento Local Installation — Composer, Sample Data and Developer Modes

In this tutorial, you'll learn how to install Magento locally using Composer, configure your system with all required services, and set up the development environment with sample data and developer mode.

What You'll Learn

• Magento system requirements for PHP, MySQL, Elasticsearch, Redis, and Composer
• How to generate authentication keys in the Magento Marketplace
• Using Composer to create a Magento project
• Setting file permissions and the Magento file system owner
• Installing sample data for a realistic development catalog
• Running the Magento installation wizard via CLI
• Configuring developer mode, compilation, and static content deployment
• Setting up Nginx for Magento with the sample configuration

Why It Matters

A proper local installation is the foundation of all Magento development work. If your local environment does not match production requirements, you will encounter bugs, performance issues, and deployment failures. Installing Magento correctly the first time teaches you the directory structure, configuration files, and CLI tools you will use every day as a developer. Mistakes in this step waste hours of debugging later.

Real-World Use

A developer joins a team maintaining a Magento store with 5,000 products, B2B pricing, and custom modules. Before making any changes, they need a local environment that mirrors production exactly. The same installation process they use today — Composer, sample data, developer mode — will be the foundation for every future project they work on.

Learning Path

flowchart LR
  A["What is Magento?"] --> B["Local Installation
← You are here"]:::current
  B --> C["Admin Dashboard"]
  C --> D["Magento Hosting"]
  D --> E["Product Types"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

System Requirements

Before installing Magento, your system must meet these requirements. Magento 2.4.7 (the latest stable version as of this writing) requires:

It is best to verify your PHP version first:

php -v

This should show PHP 8.2 or higher. You also need these PHP extensions installed: bcmath, ctype, curl, dom, gd, hash, iconv, intl, mbstring, openssl, pdo_mysql, simplexml, soap, xsl, zip, sockets, sodium.

Magento also requires a search engine — Elasticsearch or OpenSearch — running on your system. You can install it via Docker or natively. Redis for cache and session storage is highly recommended even in development.

Authentication Keys

Magento's Composer repository requires authentication. You must generate authentication keys in your Magento Marketplace account before you can download any packages.

1. Go to https://marketplace.magento.com and log in or create an account.
2. Navigate to your account profile and click Access Keys.
3. Create a new key pair. You get a public key and a private key.
4. Store the keys in an auth.json file in your project root or in ~/.composer/auth.json.

The auth.json file looks like this:

{
    "http-basic": {
        "repo.magento.com": {
            "username": "your-public-key",
            "password": "your-private-key"
        }
    }
}

These keys allow Composer to authenticate with repo.magento.com and download Magento packages. Without them, the composer create-project command will fail.

Creating the Magento Project

With Composer installed and authentication configured, create the Magento project:

composer create-project --repository-url=https://repo.magento.com/ magento/project-community-edition /var/www/magento2

This downloads Magento Open Source and all its dependencies into the /var/www/magento2 directory. The process takes several minutes because Composer resolves and downloads hundreds of packages.

For the enterprise edition, replace project-community-edition with project-enterprise-edition. You need access to the private enterprise repository.

File Permissions

Magento needs proper file permissions to write to the var/ and generated/ directories. The recommended setup uses a single user for both the web server and the CLI:

sudo chown -R www-data:www-data /var/www/magento2
sudo find /var/www/magento2 -type d -exec chmod 770 {} \;
sudo find /var/www/magento2 -type f -exec chmod 660 {} \;
sudo chmod +x bin/magento

Set the umask to 002 so that newly created files inherit group-writable permissions:

echo "umask 002" >> ~/.bashrc
source ~/.bashrc

This prevents permission problems where the web server cannot write to cache or session directories.

Installing Sample Data

Sample data gives you products, categories, customers, and orders to work with during development. Instead of creating everything manually, use the sample data deployment tool:

cd /var/www/magento2
php bin/magento sampledata:deploy

This runs a Composer operation that installs sample data modules. After deployment, you need to run the full installation process for the sample data to be imported into the database.

If you skip this step, you will have an empty store with no products. You can install sample data later, but it is easier to do it before the main installation.

Running the Installation

Magento provides a CLI installation command that handles database creation, configuration generation, and admin user setup:

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

Each parameter has a specific purpose:

• --base-url is the URL where your Magento store will be accessible. For local development, this is usually a domain like magento2.local that you have configured in your hosts file.
• --db-host, --db-name, --db-user, --db-password configure the database connection. The database must exist before running this command.
• --admin-firstname, --admin-lastname, --admin-email, --admin-user, --admin-password create the initial admin user.
• --language, --currency, --timezone set the default store configuration.
• --use-rewrites=1 enables Apache/Nginx rewrites for clean URLs.
• --search-engine and --elasticsearch-host configure the search engine, which is mandatory for Magento 2.4+.

If the command succeeds, you will see a success message with the admin URL and access tokens.

Developer Mode

Magento runs in default mode after installation. For development, you should switch to developer mode:

php bin/magento deploy:mode:set developer

Developer mode provides:

• Static file Caching is disabled — changes to CSS, Less, and JavaScript appear immediately
• Exceptions display detailed stack traces in the browser
• Logging is more verbose
• Template hints can be enabled via the admin panel

In production, you use production mode which enables static content caching, compiles Dependency Injection configuration, and disables detailed error messages.

Compilation and Static Content Deployment

After installation, compile the dependency injection configuration:

php bin/magento setup:di:compile

This generates all interceptor classes, factories, and proxies. Without compilation, the store loads slowly and some features may not work correctly.

Deploy static content for the admin theme and the storefront:

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

The -f flag forces redeployment of all static files even if they already exist. In developer mode, this step is optional because files are generated on the fly, but running it ensures your installation is complete.

Nginx Configuration

Magento ships with an optimized Nginx configuration sample. Copy it to your site configuration:

server {
    listen 80;
    server_name magento2.local;
    set $MAGE_ROOT /var/www/magento2;
    include /var/www/magento2/nginx.conf.sample;
}

The nginx.conf.sample file includes all the rewrite rules for clean URLs, static file handling, and PHP-FPM passthrough. It sets up the X-Forwarded-Proto header, handles maintenance pages, and configures caching headers for static assets.

The key line is the passthrough to index.php:

location / {
    try_files $uri $uri/ /index.php?$args;
}

This means all requests that do not match a real file are forwarded to Magento's entry point.

Verifying Your Installation

After installation, you can verify the setup by visiting:

• Storefront: http://magento2.local
• Admin panel: http://magento2.local/admin

Log in with the admin credentials you provided during installation. The admin user should be able to access the dashboard, see products (if sample data was installed), and navigate all menus.

If you see a 404 on the admin page, the admin path may be different. Check the installation output for the exact admin URL.

Common Mistakes

1. Missing PHP extensions. Installing Magento without all required PHP extensions causes cryptic errors during installation or page load. Always verify your PHP extension list before starting.

2. Elasticsearch not running. Magento 2.4 requires a search engine. If you skip Elasticsearch or OpenSearch, the installation fails with a search engine error. Ensure the service is running and accessible on the configured port.

3. Wrong file permissions. Setting incorrect permissions on var/ and generated/ directories causes write errors during cache cleaning, compilation, and static content deployment. The web server user must have write access.

4. Skipping sample data. Installing without sample data leaves you with an empty catalog. You waste time creating test products manually instead of focusing on learning the platform's features.

5. Using default mode for development. Keeping the store in default mode means static file caching obscures your changes. Always switch to developer mode before starting development work.

Practice Questions

1. What is the purpose of the auth.json file in a Magento installation? Answer: The auth.json file stores your Magento Marketplace authentication keys, which are needed by Composer to download packages from repo.magento.com. Without these keys, the composer create-project command cannot authenticate and fails.

2. Why is Elasticsearch or OpenSearch required for Magento 2.4+? Answer: Magento 2.4 removed the built-in MySQL search and requires an external search engine for catalog search. Elasticsearch or OpenSearch handle full-text search, faceted navigation, and search relevance ranking. The database cannot efficiently perform these operations at scale.

3. What is the difference between developer mode and default mode? Answer: Developer mode disables static file caching so CSS, JavaScript, and Less changes appear immediately without redeployment. It also shows detailed exception messages. Default mode caches static files and shows generic error pages, which is unsuitable for development.

4. Challenge: Set up a Magento installation script that accepts environment variables for database credentials, admin user details, and search engine configuration. The script should handle authentication key prompts, run the Composer installation, configure permissions, install sample data, run the CLI installation, and set developer mode. Test it on a fresh VM or Docker container.

FAQ

{{< faq "Can I install Magento on shared hosting?" "No. Magento requires dedicated servers with PHP 8.2+, command-line access, Elasticsearch/OpenSearch, Redis, and significant memory. Shared hosting environments do not provide these resources. Use a VPS, dedicated server, or {{< ilink "Magento" "Magento Cloud" >}} instead." >}}

Mini Project

Your task: Automate a complete Magento local installation.

1. Set up a local development environment with PHP 8.2, MySQL 8, Elasticsearch 8, Redis 7, and Nginx on your machine or a Docker container.
2. Generate authentication keys from the Magento Marketplace and create an auth.json file.
3. Use Composer to create a Magento Open Source project with sample data.
4. Create a bash script that runs the complete CLI installation with your preferred configuration.
5. After installation, verify the storefront and admin panel are accessible.
6. Enable developer mode and run compilation.
7. Create a README document with your installation steps, configuration settings, and troubleshooting notes.

This exercise gives you a repeatable installation process you can use for every Magento project.

What's Next

Now that Magento is installed locally, explore the admin panel to understand the management interface:

Continue to Lesson 3: Admin Dashboard Tour — Navigate every menu and section.

Related lessons:

• Magento Hosting — Configure your server for production
• What is Magento — Understand the platform architecture
• PHP for Magento — Learn Magento-specific PHP patterns