Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 42 ยท Getting Started

Setting Up a Development Environment

Set up a local Magento 2.4 environment: required services, Composer install with Marketplace keys, the setup:install command, file permissions and Docker options.

Installing Magento is the first real hurdle for newcomers, because the software needs several services running at the same time and each of them has version limits. The good news is that the steps are always the same: prepare the services, download the code with Composer, run one install command, and fix permissions. Once it works, you rarely repeat it, since each project folder keeps its own environment.

This lesson walks through each step conservatively. Exact version numbers differ between 2.4.x releases, so treat any number you read in a tutorial (including this one) as an example and confirm it on the system requirements page of the release you install. Everything that touches a real installation is shown read-only. Two small stand-ins at the end let you practise the checking logic and the command building in plain PHP.

What Magento needs

A working installation needs these services:

Service Role Notes
PHP with extensions Runs the application The release lists the supported PHP versions and required extensions (for example intl, bcmath, gd, soap, xsl, zip, sodium)
MySQL or MariaDB Stores catalog, customers, orders Supported versions are listed per release
OpenSearch (or Elasticsearch in older 2.4 releases) Catalog search Required since 2.4.0, the install fails without a reachable search engine
Composer 2 Downloads Magento and modules Needed for installs and upgrades
Web server nginx or Apache, pointing at pub/ Magento ships sample configuration files
Redis or a compatible cache Cache and session storage Optional, recommended for performance
RabbitMQ Message queues Optional, otherwise MySQL-based queues are used

You can install these directly on your machine, but most teams use a container setup.

Choosing a local setup

You have three realistic choices:

  1. A Docker-based tool made for Magento, such as Warden, DDEV, or a community docker-compose template. These start the web server, PHP, database, OpenSearch and Redis with matching versions and handle HTTPS and hostnames. This is the usual recommendation, because the whole team gets the same environment from a few files in the repository.
  2. Your own docker-compose.yml. More work, but you control everything.
  3. Installing the services natively on Linux, macOS or WSL. Possible, but you have to keep every version in step yourself.

Whichever you choose, give the PHP process enough memory for Composer and for the first page loads, and keep your code on the fast side of the file system. On Windows with Docker, keep the project inside the Linux file system (WSL) rather than a mounted Windows folder, because Magento touches thousands of small files and bind-mounted folders can be very slow.

Getting the code with Composer

Magento packages are served from Adobe's own Composer repository, which requires authentication. You create an access key pair (a public and a private key) in your Adobe Commerce Marketplace account. Composer asks for them as username and password and can store them in auth.json:

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

Keep auth.json out of version control, or keep it in your home directory (~/.composer/auth.json) so it never enters the project. Then create the project:

Terminal
composer create-project --repository-url=https://repo.magento.com/ \
  magento/project-community-edition ./shop

project-community-edition is the Open Source edition. Adobe Commerce customers use a different project package with the same procedure. You can add a version constraint to install an exact release instead of the newest one. The command creates the folder layout you saw in Architecture and Directory Layout and downloads the modules into vendor/.

Running the installer

With the services running, the installer creates database tables, writes app/etc/env.php and creates the admin user:

Terminal
bin/magento setup:install \
  --base-url=http://shop.test/ \
  --db-host=db --db-name=magento --db-user=magento --db-password=secret \
  --admin-firstname=Ada --admin-lastname=Admin \
  --admin-email[email protected] \
  --admin-user=admin --admin-password='Use-a-long-passphrase-1' \
  --language=en_US --currency=USD --timezone=UTC \
  --use-rewrites=1 \
  --search-engine=opensearch \
  --opensearch-host=search --opensearch-port=9200

Notes on the options:

  • --base-url must end with a slash and must match the hostname you will open in the browser.
  • --search-engine and the matching host and port options point the installer at your search service. The engine option name and its allowed values depend on the release, so check bin/magento setup:install --help.
  • --use-rewrites=1 enables clean URLs; your web server must be configured to pass requests to pub/index.php.
  • Admin passwords have to meet Magento's strength rules, and a real project should never reuse the example values above.

For a development machine you can then switch modes and clear caches:

Terminal
bin/magento deploy:mode:set developer
bin/magento cache:flush

File permissions

Magento writes files while it runs, so the user that runs PHP must be able to write to a handful of folders: var/, generated/, pub/static/, pub/media/ and app/etc/. A safe approach is to give the files an owner (usually the PHP user or a shared group) with typical permissions of 644 for files and 755 for directories, and to add group write access only where needed:

Terminal
find var generated pub/static pub/media app/etc -type f -exec chmod g+w {} +
find var generated pub/static pub/media app/etc -type d -exec chmod g+ws {} +

Never run chmod -R 777 to make an error go away. It makes every file writable by every user on the machine. On a live server, lock app/etc down again after installation.

If you run commands as different users, for instance root in a container and www-data for PHP-FPM, you will get "permission denied" errors on cache and generated files. Run bin/magento commands as the same user that runs the web server.

First checks after installing

Open the storefront at your base URL, then open the admin. The admin URL is not /admin by default in new installs: the installer chooses a random path, and bin/magento info:adminuri prints it. Create a sample product, flush the cache with bin/magento cache:flush, and look in var/log/ if anything fails.

Two stand-ins follow. The first mimics a requirements checker using version_compare() and extension lists; the second builds the install command from options and masks the secrets before printing it, a good habit for CI logs.

PHP A requirements checker

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Building a setup:install command safely

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which service must be reachable for setup:install to succeed on Magento 2.4?

    Since 2.4.0 catalog search needs a search engine, so the installer expects one. Varnish, RabbitMQ and Redis are optional.
  2. 2. What do the Marketplace access keys do?

    The public and private key act as username and password for Adobe's Composer repository, usually stored in auth.json.
  3. 3. What is the right response to a permission error on var/ or generated/?

    Fix ownership and group permissions on the folders Magento writes to. 777 is unsafe, and mismatched users cause the errors in the first place.
  4. 4. Why keep the project inside the Linux file system when using Docker on Windows?

    Bind-mounted folders add large overhead for many small file operations, which makes Magento painfully slow.

Summary

  • Magento needs PHP, a database, a search engine and Composer; Redis and RabbitMQ are optional.
  • A Docker-based Magento setup is the most reproducible choice for teams.
  • Authenticate Composer with Marketplace keys and keep auth.json out of version control.
  • bin/magento setup:install creates the database, env.php and the admin user; check --help for your release.
  • Fix permissions with correct ownership and group write access, never 777, and serve pub/ only.

Next: Your First Module