Documentation Commerce Installation Guide

[On-premises]{class="badge informative" title="Applies to Adobe Commerce on-premises projects only."}

Install Nginx for on-premises deployments nginx

Last update: Thu Mar 26 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

Experienced
Admin
Developer

This guide walks you through installing Nginx for Adobe Commerce on-premises deployments and configuring the Nginx settings that Commerce requires. It includes operating system-specific procedures for Ubuntu and CentOS, along with guidance for configuring PHP-FPM. Adobe recommends following the configuration instructions provided in this guide to preserve both the functionality and security of the Commerce application.

Adobe supports the Nginx versions listed in the system requirements for your Adobe Commerce release. Supported versions vary by release. Nginx also requires a supported PHP-FPM configuration. For related PHP requirements, see PHP.

Install on Ubuntu

Use this section to install Adobe Commerce on Ubuntu with Nginx, PHP, and MySQL.

Install Nginx

sudo apt -y install nginx

You can also build Nginx from source.

After you complete the following sections and install the application, use the sample configuration file to configure Nginx. This recommended configuration preserves both the functionality and security of the Commerce application.

Install and configure PHP-FPM

Adobe Commerce requires several PHP extensions to function properly. In addition to these extensions, you must also install and configure the php-fpm extension if you are using Nginx.

To install and configure php-fpm:

Install the php-fpm and php-cli packages for the PHP version supported by your Adobe Commerce release. On Ubuntu, package names typically follow this pattern:

code language-bash
`apt-get -y install php<php-version>-fpm php<php-version>-cli`

note note
NOTE
Replace `<php-version>` with the supported PHP minor version listed in system requirements for the Adobe Commerce release you are installing. Use the same value in the file paths, service name, and socket path in the following steps.

Open the php.ini files in an editor:

code language-bash
`vim /etc/php/<php-version>/fpm/php.ini`

code language-bash
`vim /etc/php/<php-version>/cli/php.ini`

Edit both files to match the following lines:

code language-conf
`memory_limit = 2G max_execution_time = 1800 zlib.output_compression = On`

note note
NOTE
Adobe recommends setting the memory limit to 2 GB when testing Adobe Commerce. Refer to Required PHP settings for more information.

Save and exit the editor.

Restart the php-fpm service:

code language-bash
`systemctl restart php<php-version>-fpm`

Install and configure MySQL

Refer to MySQL for more information.

Install Adobe Commerce

You can download Adobe Commerce in several ways:

This example shows a Composer-based installation using the command line.

As the file system owner, log in to your application server.

Change to the web server docroot directory or a directory that you have configured as a virtual host docroot. For this example, we’re using the Ubuntu default /var/www/html.

code language-bash
`cd /var/www/html`

Install Composer globally. Composer is required to update dependencies before installing Adobe Commerce:

code language-bash
`curl -sS https://getcomposer.org/installer \| sudo php -- --install-dir=/usr/bin --filename=composer`

Create a Composer project using the Adobe Commerce metapackage.

Magento Open Source

code language-bash
`composer create-project --repository=https://repo.magento.com/ magento/project-community-edition <install-directory-name>`

Adobe Commerce

code language-bash
`composer create-project --repository=https://repo.magento.com/ magento/project-enterprise-edition <install-directory-name>`

When prompted, enter your authentication keys. Your public key is your username; your private key is your password.

Set read-write permissions for the web server group before you install the application. This is necessary so that the command line can write files to the file system.

code language-bash
`cd /var/www/html/<magento install directory>`

code language-bash
`find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +`

code language-bash
`find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +`

code language-bash
`chown -R :www-data . # Ubuntu`

code language-bash
`chmod u+x bin/magento`

Install from the command line. This example assumes that the install directory is named magento2ee and that the database host is on the same machine (localhost):

code language-bash

code language-bash
bin/magento setup:install \ --base-url=http://localhost/magento2ee \ --db-host=localhost \ --db-name=<db-name> \ --db-user=<db-user> \ --db-password=<db-password> \ --backend-frontname=<backend-uri> \ --admin-firstname=<admin-first-name> \ --admin-lastname=<admin-last-name> \ --admin-email=<admin-email> \ --admin-user=<admin-user> \ --admin-password=<admin-password> \ --language=en_US \ --currency=USD \ --timezone=America/Chicago \ --use-rewrites=1 \ --search-engine=<search-engine-value> \ --<search-engine-host-parameter>=search-host.example.com \ --<search-engine-port-parameter>=9200

bin/magento setup:install \
--base-url=http://localhost/magento2ee \
--db-host=localhost \
--db-name=<db-name> \
--db-user=<db-user> \
--db-password=<db-password> \
--backend-frontname=<backend-uri> \
--admin-firstname=<admin-first-name> \
--admin-lastname=<admin-last-name> \
--admin-email=<admin-email> \
--admin-user=<admin-user> \
--admin-password=<admin-password> \
--language=en_US \
--currency=USD \
--timezone=America/Chicago \
--use-rewrites=1 \
--search-engine=<search-engine-value> \
--<search-engine-host-parameter>=search-host.example.com \
--<search-engine-port-parameter>=9200

note note
NOTE
Use the `--search-engine` value and matching host/port options required by the Adobe Commerce release you are installing. For versions earlier than 2.4.6, use `elasticsearch7` with the `--elasticsearch-*` options for Elasticsearch 7 or OpenSearch. For version 2.4.6 and later, use the search engine value and corresponding CLI options supported by that release.

Switch to developer mode:

code language-bash
`cd /var/www/html/magento2/bin`

code language-bash
`./magento deploy:mode:set developer`

Configure Nginx

Adobe recommends configuring Nginx using the nginx.conf.sample configuration file provided in the installation directory and your Nginx virtual host configuration to preserve both the functionality and security of the Commerce application.

IMPORTANT

The nginx.conf.sample file provides required application routing as well as security-hardening rules. For example, it restricts execution of harmful scripts uploaded to the server. If you do not use this file or modify its rules, you are responsible for implementing equivalent security controls in your custom nginx configuration.

These instructions assume that you are using the Ubuntu default location for the Nginx virtual host, such as /etc/nginx/sites-available, and the Ubuntu default docroot, such as /var/www/html. You can change these locations to suit your environment.

Create a new virtual host for your site:

code language-bash
`vim /etc/nginx/sites-available/magento`

Add the following configuration:

code language-conf

code language-conf
`upstream fastcgi_backend { server unix:/run/php/php<php-version>-fpm.sock; } server { listen 80; server_name www.magento-dev.com; set $MAGE_ROOT /var/www/html/magento2; include /var/www/html/magento2/nginx.conf.sample; }`

upstream fastcgi_backend {
  server  unix:/run/php/php<php-version>-fpm.sock;
}

server {

  listen 80;
  server_name www.magento-dev.com;
  set $MAGE_ROOT /var/www/html/magento2;
  include /var/www/html/magento2/nginx.conf.sample;
}

note note
NOTE
The `include` directive must point to the sample nginx configuration file in your installation directory.

Replace www.magento-dev.com with your domain name. This must match the base URL you specified when installing Adobe Commerce.
Save and exit the editor.

Activate the newly created virtual host by creating a symlink to it in the /etc/nginx/sites-enabled directory:

code language-bash
`ln -s /etc/nginx/sites-available/magento /etc/nginx/sites-enabled`

Verify that the syntax is correct:

code language-bash
`nginx -t`

Restart Nginx:

code language-bash
`systemctl restart nginx`

Verify the installation

To verify the installation, open a web browser and navigate to your site’s base URL. For more information, see Verify the installation.

Install on CentOS 7

Use this section to install Adobe Commerce on CentOS 7 with Nginx, PHP, and MySQL.

Install Nginx

yum -y install epel-release

yum -y install nginx

After installation is complete, start nginx and configure it to start at boot time:

systemctl start nginx

systemctl enable nginx

After you complete the following sections and install the application, use a sample configuration file to configure Nginx.

Install and configure PHP-FPM

Adobe Commerce requires several PHP extensions to function properly. In addition to these extensions, you must also install and configure the php-fpm extension if you are using Nginx.

Install php-fpm:

code language-bash
`yum -y install <php-fpm-package>`

Open the /etc/php.ini file in an editor.

note note
NOTE
Install the package that provides `php-fpm` for the PHP version supported by the Adobe Commerce release you are installing. Package names vary by repository and operating system. See system requirements.

Uncomment the cgi.fix_pathinfo line and change the value to 0.

Edit the file to match the following lines:

code language-conf
`memory_limit = 2G max_execution_time = 1800 zlib.output_compression = On`

note note
NOTE
Adobe recommends setting the memory limit to 2 GB when testing Adobe Commerce. Refer to Required PHP settings for more information.

Uncomment the session path directory and set the path:

code language-conf
`session.save_path = "/var/lib/php/session"`

Save and exit the editor.
Open /etc/php-fpm.d/www.conf in an editor.

Edit the file to match the following lines:

code language-conf
`user = nginx group = nginx listen = /run/php-fpm/php-fpm.sock listen.owner = nginx listen.group = nginx listen.mode = 0660`

Uncomment the environment lines:

code language-conf
`env[HOSTNAME] = $HOSTNAME env[PATH] = /usr/local/bin:/usr/bin:/bin env[TMP] = /tmp env[TMPDIR] = /tmp env[TEMP] = /tmp`

Save and exit the editor.

Create a directory for the PHP session path and change the owner to the nginx user and group:

code language-bash
`mkdir -p /var/lib/php/session/`

code language-bash
`chown -R nginx:nginx /var/lib/php/`

Create a directory for the PHP-FPM socket and change the owner to the nginx user and group:

code language-bash
`mkdir -p /run/php-fpm/`

code language-bash
`chown -R nginx:nginx /run/php-fpm/`

Start the php-fpm service and configure it to start at boot time:

code language-bash
`systemctl start php-fpm`

code language-bash
`systemctl enable php-fpm`

Verify that the php-fpm service is running:

code language-bash
`netstat -pl \| grep php-fpm.sock`

Install and configure MySQL

Refer to MySQL for more information.

Install Adobe Commerce

You can download Adobe Commerce in several ways:

This example shows a Composer-based installation using the command line.

As the file system owner, log in to your application server.

Change to the web server docroot directory or a directory that you have configured as a virtual host docroot. For this example, use the CentOS default /usr/share/nginx/html.

code language-bash
`cd /usr/share/nginx/html`

Install Composer globally. Composer is required to update dependencies before installing Adobe Commerce:

code language-bash
`curl -sS https://getcomposer.org/installer \| sudo php -- --install-dir=/usr/bin --filename=composer`

Create a Composer project using the Adobe Commerce metapackage.

Magento Open Source

code language-bash
`composer create-project --repository=https://repo.magento.com/ magento/project-community-edition <install-directory-name>`

Adobe Commerce

code language-bash
`composer create-project --repository=https://repo.magento.com/ magento/project-enterprise-edition <install-directory-name>`

When prompted, enter your authentication keys. Your public key is your username; your private key is your password.

Set read-write permissions for the web server group before you install the application. This is necessary so that the command line can write files to the file system.

code language-bash
`cd /usr/share/nginx/html/<magento install directory>`

code language-bash
`find var generated vendor pub/static pub/media app/etc -type f -exec chmod g+w {} +`

code language-bash
`find var generated vendor pub/static pub/media app/etc -type d -exec chmod g+ws {} +`

code language-bash
`chown -R :nginx . # CentOS`

code language-bash
`chmod u+x bin/magento`

Install from the command line. This example assumes that the install directory is named magento2ee and that the database host is on the same machine (localhost):

code language-bash

code language-bash
`bin/magento setup:install \ --base-url=http://localhost/magento2ee \ --db-host=localhost \ --db-name=<db-name> \ --db-user=<db-user> \ --db-password=<db-password> \ --backend-frontname=<backend-uri> \ --admin-firstname=<admin-first-name> \ --admin-lastname=<admin-last-name> \ --admin-email=<admin-email> \ --admin-user=<admin-user> \ --admin-password=<admin-password> \ --language=en_US \ --currency=USD \ --timezone=America/Chicago \ --use-rewrites=1`

bin/magento setup:install \
--base-url=http://localhost/magento2ee \
--db-host=localhost \
--db-name=<db-name> \
--db-user=<db-user> \
--db-password=<db-password> \
--backend-frontname=<backend-uri> \
--admin-firstname=<admin-first-name> \
--admin-lastname=<admin-last-name> \
--admin-email=<admin-email> \
--admin-user=<admin-user> \
--admin-password=<admin-password> \
--language=en_US \
--currency=USD \
--timezone=America/Chicago \
--use-rewrites=1

Switch to developer mode:

code language-bash
`cd /usr/share/nginx/html/magento2/bin`

code language-bash
`./magento deploy:mode:set developer`

Configure Nginx

We recommend configuring Nginx using the nginx.conf.sample file in the installation directory and your Nginx virtual host configuration.

IMPORTANT

These instructions assume that you are using the CentOS default location for the Nginx virtual host, such as /etc/nginx/conf.d, and the default docroot, such as /usr/share/nginx/html. You can change these locations to suit your environment.

Create a new virtual host for your site:

code language-bash
`vim /etc/nginx/conf.d/magento.conf`

Add the following configuration:

code language-conf

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

server {

  listen 80;
  server_name www.magento-dev.com;
  set $MAGE_ROOT /usr/share/nginx/html/magento2;
  include /usr/share/nginx/html/magento2/nginx.conf.sample;
}

note note
NOTE
The `include` directive must point to the sample nginx configuration file in your installation directory.

Replace www.magento-dev.com with your domain name.
Save and exit the editor.

Verify that the syntax is correct:

code language-bash
`nginx -t`

Restart Nginx:

code language-bash
`systemctl restart nginx`

Configure SELinux and firewalld

SELinux is enabled by default on CentOS 7. Use the following command to confirm it is running:

sestatus

To configure SELinux and firewalld:

Install SELinux management tools:

code language-bash
`yum -y install policycoreutils-python`

Run the following commands to change the security context for the installation directory:

code language-bash
`semanage fcontext -a -t httpd_sys_rw_content_t '/usr/share/nginx/html/magento2/app/etc(/.*)?'`

code language-bash
`semanage fcontext -a -t httpd_sys_rw_content_t '/usr/share/nginx/html/magento2/var(/.*)?'`

code language-bash
`semanage fcontext -a -t httpd_sys_rw_content_t '/usr/share/nginx/html/magento2/pub/media(/.*)?'`

code language-bash
`semanage fcontext -a -t httpd_sys_rw_content_t '/usr/share/nginx/html/magento2/pub/static(/.*)?'`

code language-bash
`restorecon -Rv '/usr/share/nginx/html/magento2/'`

Install the firewalld package:

code language-bash
`yum -y install firewalld`

Start the firewall service and configure it to start at boot time:

code language-bash
`systemctl start firewalld`

code language-bash
`systemctl enable firewalld`

Run the following commands to open ports for HTTP and HTTPS so you can access the base URL from a web browser:

code language-bash
`firewall-cmd --permanent --add-service=http`

code language-bash
`firewall-cmd --permanent --add-service=https`

code language-bash
`firewall-cmd --reload`

Verify the installation

To verify the installation, open a web browser and navigate to your site’s base URL. For more information, see Verify the installation.

recommendation-more-help

0f8e7db5-0e9c-4002-a5b8-a0088077d995