DocumentationCommerceInstallation Guide

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

Install Apache for on-premises deployments apache

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 Apache for Adobe Commerce on-premises deployments and configuring the Apache settings that Commerce requires. It includes shared Apache requirements and operating system-specific procedures for Ubuntu and CentOS. Adobe recommends following the configuration instructions provided in this guide to preserve both the functionality and security of the Commerce application.

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

Start with the section that matches your environment:

Review Apache requirements

Complete these requirements on any Apache server that hosts Adobe Commerce.

Configure required directives

Set AllowEncodedSlashes in the server config (globally) or in the virtual host configurations to avoid decoding the encoded slashes that can cause issues for URLs. For example, when retrieving products with a slash in the SKU via the API, you do not want the slash converted. The following example block is not complete and other directives are required.

<VirtualHost *:443>
  # Allow encoded slashes
  AllowEncodedSlashes NoDecode
</VirtualHost>

Configure rewrites and .htaccess apache-rewrites-and-htaccess

Use this section to enable Apache rewrites and configure the distributed .htaccess file. Adobe Commerce uses server rewrites and .htaccess to provide directory-level instructions for Apache.

IMPORTANT
Failure to enable these settings typically results in no styles displaying on your storefront or Admin. It can also prevent Apache from applying the Adobe Commerce security protections defined in .htaccess.

  1. Enable the Apache rewrite module:

    code language-bash 
    a2enmod rewrite

  2. Enable the application to use the distributed .htaccess configuration file.

    1. On Ubuntu, edit /etc/apache2/sites-available/000-default.conf. For other Apache layouts or if additional parameters are required, see the Apache documentation and the Apache access control documentation.

    2. Add or update the AllowOverride directive for the directory where you plan to install Adobe Commerce.

    For example, if you install Adobe Commerce in the default docroot, add the following block to 000-default.conf:

    code language-conf 
    <Directory "/var/www/html">
  AllowOverride All
</Directory>
    note note
    NOTE
    If you upgraded from an earlier Apache version, first look for an existing <Directory "/var/www/html"> or <Directory "/var/www"> block in 000-default.conf. If you install Adobe Commerce in a different docroot, update the matching <Directory> block for that path.

  3. Restart Apache to apply your changes:

    code language-bash 
    service apache2 restart

Install required modules

Adobe Commerce requires the following Apache modules to be installed:

Verify Apache is installed

To verify that Apache is installed and view the current version, enter:

apache2 -v

The result displays information similar to the following:

Server version: Apache/<installed-version>
Server built: <build-date>

Install or upgrade Apache on Ubuntu installing-or-upgrading-apache-on-ubuntu

Installing and configuring Apache on Ubuntu is a three-step process:

  1. Install the software.
  2. Enable rewrites.
  3. Specify .htaccess directives.

When you configure Apache server rewrites, you must specify the type of directives that can be used in .htaccess, which the application uses to specify rewrite rules and security protections.

Install Apache on Ubuntu

  1. Install Apache if you have not already done so:

    code language-bash 
    apt-get -y install apache2

  2. Verify the installation:

    code language-bash 
    apache2 -v

    Messages similar to the following display to confirm that the installation was successful:

    code language-text 
    Server version: Apache/<installed-version>
Server built: <build-date>

  3. Continue with the next section.

    note note
    NOTE
    Even if Apache is provided by default with Ubuntu, see the following section to configure it.

Upgrade Apache on Ubuntu

If Apache is already installed and you are using a version earlier than 2.4, upgrade to Apache 2.4 or to the latest version supported by the Adobe Commerce version you have deployed. See system requirements.

  1. Update package information:

    code language-bash 
    apt-get -y update

  2. Add a repository that provides a supported Apache version for your environment, if needed.

  3. Install or upgrade Apache:

    code language-bash 
    apt-get install -y apache2
    note note
    NOTE
    If the apt-get install command fails because of unmet dependencies, consult your operating system package documentation or distribution support resources.

  4. Verify the installation:

    code language-bash 
    apache2 -v

  5. Confirm that the installed version matches the version supported for your Adobe Commerce release in system requirements.

  6. Enable rewrites and .htaccess for Ubuntu.

Enable rewrites and .htaccess for Ubuntu

  1. Open the /etc/apache2/sites-available/000-default.conf file for editing:

    code language-bash 
    vim /etc/apache2/sites-available/000-default.conf

  2. Locate the block that starts with:

    code language-conf 
    <Directory "/var/www/html">

  3. Change the value of AllowOverride to All.

    For example:

    code language-conf 
    <Directory "/var/www/html">
  Options Indexes FollowSymLinks MultiViews
  AllowOverride All
  Order allow,deny
  Allow from all
</Directory>

  4. Save the file and exit the text editor.

  5. Configure Apache to use the mod_rewrite module:

    code language-bash 
    cd /etc/apache2/mods-enabled
    code language-bash 
    ln -s ../mods-available/rewrite.load

  6. Restart Apache to apply changes:

    code language-bash 
    service apache2 restart
IMPORTANT
Failure to enable these settings typically results in no styles displaying on your storefront or Admin. It can also prevent Apache from applying the Adobe Commerce security protections defined in .htaccess.

Install Apache on CentOS installing-apache-on-centos

Installing and configuring Apache on CentOS is a three-step process:

  1. Install the software
  2. Enable rewrites
  3. Specify .htaccess directives.

When you configure Apache server rewrites, you must specify the type of directives that can be used in .htaccess, which the application uses to specify rewrite rules and security protections.

Installing Apache

  1. Install Apache if you have not already done so.

    code language-bash 
    yum -y install httpd

  2. Verify the installation:

    code language-bash 
    httpd -v

    Messages similar to the following display to confirm that the installation was successful:

    code language-text 
    Server version: Apache/<installed-version>
Server built: <build-date>

  3. Continue with the next section.

    note note
    NOTE
    Even if Apache is provided by default with CentOS, see the following section to configure it.

Enable rewrites and .htaccess for CentOS

  1. Open the /etc/httpd/conf/httpd.conf file for editing:

    code language-bash 
    vim /etc/httpd/conf/httpd.conf

  2. Locate the block that starts with:

    code language-conf 
    <Directory "/var/www/html">

  3. Change the value of AllowOverride to All.

    For example:

    code language-conf 
    <Directory "/var/www/">
  Options Indexes FollowSymLinks MultiViews
  AllowOverride All
  Order allow,deny
  Allow from all
</Directory>
    note note
    NOTE
    The preceding values for Order might not work in all cases. For more information, see the Apache documentation.

  4. Save the file and exit the text editor.

  5. To apply the Apache settings, restart Apache.

    code language-bash 
    systemctl restart httpd
IMPORTANT
Failure to enable these settings typically results in no styles displaying on your storefront or Admin. It can also prevent Apache from applying the Adobe Commerce security protections defined in .htaccess.

Solving 403 (Forbidden) errors

If you encounter 403 Forbidden errors when trying to access the site, you can update your Apache configuration or your virtual host configuration to enable visitors to the site:

Solve 403 Forbidden errors for Apache

To enable website visitors to access your site, use one of the Require directives.

For example:

<Directory "/var/www/">
  Options Indexes FollowSymLinks MultiViews
  AllowOverride All
  Order allow,deny
  Require all granted
</Directory>
NOTE
The preceding values for Order might not work in all cases. For more information, see the Apache documentation.
recommendation-more-help
0f8e7db5-0e9c-4002-a5b8-a0088077d995