Migrating a Magento Installation from Apache2 to NGINX on Debian Stretch

May 20, 2019 @ 3:42 pm

Apache2, debian, Magento, nginx, PHP-FPM

Magento is one of the worlds leading e-commerce CMS solutions and is used by over 200K websites. What makes Magento such an appealing e-commerce CMS is that Magento offers a free, community edition of their platform. Anyone with some Linux knowledge and access to a modest virtual machine can get their online store up and running in no time. Magento runs on a Linux stack giving wide flexibility on the open source components that are used to power the store. The typical first choice for a Linux web server is usually Apache which makes for a stable and dependable choice. However, there are other options that can offer greater performance with lower system resource usage. One popular such alternative is NGINX.

In this guide, we will walk through the process of migrating an existing Magento installation from Apache to NGINX on Debian Stretch.

Prerequisites

In order to follow this guide you will need the following:

A Debian Stretch Server
A Magento installation.
A non-root sudo user account on the Magento server.

In order to begin this guide, you need to log into your server as a non-root sudo enabled user.

Put Magento in Maintenance Mode

During this guide, we will be stopping and starting the web servers which will make your Magento store appear and disappear for any user accessing it. This is not a great experience for your clients we will avoid this issue by putting Magento into maintenance mode. When Magento is in maintenance mode any visitor will see a holding page and will not be able to interact with your store.

You put Magento into maintenance mode by running the following command:

sudo php /path/to/magento2/bin/magento maintenance:enable --ip=<YOUR IP>

The --ip=<YOUR IP> option will allow you to access your store from your IP whilst all other IP’s will see the maintenance page. This will allow you to view and check that the store is working whilst still maintaining maintenance mode for visitors.

Now that Magento is in maintenance mode we can install NGINX.

Installation NGINX and PHP-FPM

In this step, we will install NGINX and the PHP-FPM packages. NGINX uses PHP-FPM which is a performant re-implementation of standard PHP. If you are already using PHP-FPM with Apache you can remove it from the apt-get install command but leaving it in place will not cause a problem.

We should stop Apache here or the installation will encounter an error when APT attempts to start NGINX while Apache is running. The following commands will stop Apache running and disable it from stating on boot:

sudo systemctl stop apache2.service
sudo systemctl disable apache2.service

Run the following command to install NGINX and PHP-FPM:

sudo apt-get install nginx php-fpm

NGINX is now installed and ready for configuration.

Migrating an HTTP Only Magento Instance

In this step, we will configure NGINX to serve only an HTTP Magento instance. If your Magento instance uses HTTPS then skip ahead to the next section which covers migrating an HTTPS Magento instance.

NGINX works like Apache in that it has two directories /etc/nginx/sites-available and /etc/nginx/sites-enabled that contain the web server configuration to serve your store. We will first place the configuration file into /etc/nginx/sites-available and then create a symlink to that file in /etc/nginx/sites-enabled which will allow NGINX to start serving your site.

We will create and edit the site configuration file using a text editor. I will use nano throughout this guide but you can use whichever you are most comfortable with:

sudo nano /etc/nginx/sites-available/magento.conf

The contents of this file should look like the following basic example (remember you need to change exmaple.com and /var/www/magento2 to match your setup):

server {
   listen 80;
   server_name <YOUR STORE URL>;
   set $MAGE_ROOT /path/to/magento2;
   include /path/to/magento2/nginx.conf.sample;
}

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

The above configuration assumes that you are using PHP 7.0 (the default) on your server. If you are using a different version then you will need to edit the line server unix:/var/run/php/php7.1-fpm.sock; to match the version of PHP and PHP-FPM you are using. If you run:

ls /var/run/php/

You will be able to see the name of the PHP-FPM socket that you need to use.

The following line:

include /path/to/magento2/nginx.conf.sample;

Causes NGINX to load additional configuration contained in the file /path/to/magento2/nginx.conf.sample. This file is supplied by Magento and contains very important additional configuration such as blocking access to confidential files, setting compression, etc. If you don’t have a copy of this file you can download one from these locations:

Magento 2.2 – https://github.com/magento/magento2/blob/2.2/nginx.conf.sample
Magento 2.3 – https://github.com/magento/magento2/blob/2.3/nginx.conf.sample

You will need to include this file for this NGINX configuration file to serve your store.

Now that the configuration file is in place we need to enable it by creating a symlink from sites-enabled with the following command:

sudo ln -s /etc/nginx/sites-available/magento.conf /etc/nginx/sites-enabled/

Then reload NGINX:

sudo systemctl reload nginx.service

NGINX should now be serving your store. You should visit your store in a browser to check that it is working normally. If your site does not render correctly after the migration it is quite likely because of stale cache and indexed data. Flushing the cache and re-indexing the site with these two commands will resolve this issue:

sudo php /path/to/magento2/bin/magento cache:flush
sudo php /path/to/magento2/bin/magento indexer:reindex

The site should now be working normally. You should visit both the home page and the admin pages to ensure they are working as expected. The following command will disable maintenance mode and resume normal site operation:

sudo php /path/to/magento2/bin/magento maintenance:disable

Your Magento instance is now migrated to using NGINX as its webserver.

Migrating An HTTPS Magento Instance

In this step, we will configure NGINX to serve an HTTPS enabled Magento instance. NGINX works like Apache in that it has two directories /etc/nginx/sites-available and /etc/nginx/sites-enabled that contain the website configuration. We will first place the configuration file into /etc/nginx/sites-available and then create a symlink to that file in /etc/nginx/sites-enabled which will enable NGINX to start serving your store.

We will create and edit the site configuration file using a text editor. I will use nano throughout this guide but you can use whichever you are most comfortable with:

sudo nano /etc/nginx/sites-available/magento.conf

The following file will serve an HTTPS site. The first server block will automatically redirect any visitors arriving on HTTP to the HTTPS site:

server {
    listen 80;
    server_name <YOUR STORE URL>;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name <YOUR STORE URL>;

    ssl on;
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    set $MAGE_ROOT /path/to/magento2;
    include /path/to/magento2/nginx.conf.sample;
}

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

ls /var/run/php/

You will be able to see the name of the PHP-FPM socket that you need to use.

The following line:

include /path/to/magento2/nginx.conf.sample;

causes NGINX to load additional configuration contained in the file /path/to/magento2/nginx.conf.sample. This file is supplied by Magento and contains very important additional configuration such as blocking access to confidential files, setting compression etc. If you don’t have a copy of this file you can download one from these locations:

Magento 2.2 – https://github.com/magento/magento2/blob/2.2/nginx.conf.sample
Magento 2.3 – https://github.com/magento/magento2/blob/2.3/nginx.conf.sample

You will need to include this file for this NGINX configuration file to serve your store.

Now that the configuration file is in place we need to enable it by creating a symlink from sites-enabled with the following command:

sudo ln -s /etc/nginx/sites-available/magento.conf /etc/nginx/sites-enabled/

Then reload NGINX:

sudo systemctl reload nginx.service

sudo php /path/to/magento2/bin/magento cache:flush
sudo php /path/to/magento2/bin/magento indexer:reindex

sudo php /path/to/magento2/bin/magento maintenance:disable

Conclusion

Your site should now be running normally and taking advantage of the increased performance and reduced resource requirements of NGINX. If you need additional information on configuration and tuning NGINX their documentation can be found on their website here.

LowEndBoxTV: Ubuntu 24: Hot Rod Ferrari Speed Freak, Crippled Dump Truck, or Somewhere in Between?

The Mother of All Supply Chain Attacks! Is 1Password Safe?!? (UPDATED)

Examining the Top 12 Server Operating Systems of 2024: Choose the Best One for Your Needs

How to Update Debian Automatically: No Muss, No Fuss, Not At All Sus

LowEndBoxTV: Debian 12 "Bookworm" Benchmarks!

Debian 12 Bookworm Arrives June 10!

Author
Recent Posts

Liam