Install prerequisites

Previous step

Prepare for local environment setup

Install the following software packages and tools on your local workstation to prepare for code development. If you already have these packages installed, check for any recommendations or notes and continue to the next step.

To begin, install and set up a VM on your host computer (Windows, Mac OS, Linux-based system). A VM gives you an environment to install a different Operating System, tools, software, a database, and application code without requiring a customized system. You only need to install the VM software on your host. All other software can be installed and configured on your VM.

When you install and configure software on your local (or VM), you will first SSH into the VM and then complete installations. Follow the SSH instructions and commands for the VM software you install. For example, you would install PHP, Nginx, and database on the VM via SSH.

Our documentation provides installation instructions for installing software on CentOS or Ubuntu only. For installation information on Windows or MacOS, consult a community resource.

Virtual machine or container (host)

To best develop and manage your host, we recommend using a virtual machine. The VM encapsulates your code, web services, testing and supports a Unix-based environment. Select a virtual system you prefer.

For your VM, we recommend installing one of the following:

When using Vagrant, we also recommend the package hostmanager and using VirtualBox to manage the environment. VirtualBox extends support and features across all OS and platforms to create and manage multiple VMs and operating systems on your local.

Development tools

  • Git - Provides code branching and management for accessing Adobe Commerce and your code repositories. Use Git command-line commands or applications of your choice to work with Git. You can install this on your local VM or on your host. For more information, see How Cloud uses Git.
  • Composer - Used for dependency management. Composer enables us to manage Adobe Commerce components and dependencies. Install on your local VM. For more information, see How Cloud uses Composer.

Web server (local)

We strongly recommend installing Nginx for your web server on your local. While Adobe Commerce supports Apache, Adobe Commerce on cloud infrastructure uses Nginx. To have your local as close to cloud installations as possible, install and configure Nginx.

PHP (local)

Install PHP on your local workstation. For information on installing PHP, see PHP Settings. For instructions for another OS, see the PHP documentation.

The following packages may also be helpful for your PHP installation:

Set up PHP memory limit

When you’re working with the magento-cloud CLI, local environment settings come from the machine on which you’re working, not from Adobe Commerce. For example, certain actions (like debugging) require a larger PHP memory_limit than most PHP distributions provide by default.

Before working with your Adobe Commerce on cloud infrastructure project, set the PHP memory_limit to at least 1G for normal use or at least 2G for debugging.

To set a memory limit:

  1. Find your php.ini file using the following command:

    php --ini

    Use the value of Loaded Configuration File.

  2. As a user with root privileges, open php.ini in a text editor.
  3. Change the value of memory_limit to at least 1G for normal use or at least 2G for debugging.
  4. Save your changes to php.ini and exit the text editor.
  5. Restart your web server:

    • Apache:
      • CentOS: service httpd restart
      • Ubuntu: service apache2 restart
    • Nginx: service nginx restart

Database (local)

You have multiple options for databases to use for your local. One database option you may want to consider is MariaDB. The Adobe Commerce environments use MariaDB, with a Galera Cluster with triple redundancy in the Production environment.

Regardless of database, for Pro plans you need to modify the auto_increment_increment value.

For Pro plans, the Production environment has a three node infrastructure that uses auto-incrementing by 3 for all data IDs. Do not develop using hard-coded database IDs in your development. Due to the incremented data IDs, the referenced data will differ across the three nodes in Production.

To install and create a MariaDB database for Adobe Commerce on your local workstation:

  1. Use this command to create the database:

    apt-get install mariadb-server
  2. Secure the database with the following command and completing all prompts:

  3. Access the MariaDB database.
  4. Grant all privileges to the account that you created:

    grant all privileges on <database> to '<account>'@'localhost' identified by '<password>';
  5. Finally create the database:

    create database magento;
    use magento;
  6. Exit when done.

Pro: Set up the auto-increment for MariaDB

You need to set an auto-increment value for the MariaDB installation.

  1. As a user with root privileges, open /etc/mysql/mariadb.conf.d/50-server.cnf in a text editor.
  2. In the Basic Settings section, add auto_increment_increment = 3.
  3. Restart the service: service mysql restart.

Pro: Set up the auto-increment for MySQL

The MySQL configuration parameter auto_increment_increment is set to 1 by default in a local MySQL installation. You need to change this value to 3. The Adobe Commerce database cluster includes 3 database implementations. The increment ensures data is unique across all databases for consistent data in the High Availability structure.

To avoid issues, we recommend you set auto_increment_increment=3.

First, view the current value and verify if it is set to 3:

mysqladmin variables -u <root username> -p | grep 'auto_increment'

To set auto_increment_increment to 3:

  1. As a user with root privileges, open /etc/my.cnf in a text editor.

    On Ubuntu 16, the path is typically /etc/mysql/mysql.conf.d/mysqld.cnf.

  2. Add or edit the following line in the [mysqld] section:


    Adobe Commerce on cloud infrastructure supports a High Availability configuration. This setting increments the database IDs in increments of three to ensure row uniqueness for Galera databases on each of the three HA nodes in production.

  3. Restart MySQL:

    service mysqld restart

Magento Cloud CLI

To install the magento-cloud CLI , see the Magento Cloud CLI reference.

Additional requirements

The requirements listed in this topic are specific to Adobe Commerce on cloud infrastructure environments. You will also install Adobe Commerce on your VM or Docker container. For that installation, you should also review the following:

Additional options

You can also install additional optional software. These packages should be installed on the local VM.

Next step

Enable SSH keys