How to use Nginx

in Nginx configuration

One of the biggest differences between Hypernode and more traditional platforms, such as Byte’s Shared Magento hosting, is the use of Nginx (pronunciation: ‘Engine X’) over Apache. Nginx has much better performance than Apache, and allows us to serve your webshop to many more visitors than Apache would.

Magento specific Nginx configuration

As your Hypernode is designed from the ground up to host Magento, we’ve taken great care to tweak the Nginx server for optimal performance and usability. We’ve moved all the Magento specific settings we’ve learned over the years, and the ones that Magento Inc. suggests, and includes in its .htaccess file, into the main Nginx configuration. Then we added a layer of protection against malicious bots and hackers, and a modern, JSON based logging format.

Extending Nginx configuration

Nginx does not use .htaccess files like Apache does. This means that configuration previously done in .htaccess files now has to be done in a different format, explained in the nginx documentation.

Custom configuration to Nginx can be made by placing files in the /data/web/nginx directory inside your home directory.

Inclusion order

The inclusion order of files in /data/web/nginx is as follows:

  • Files starting with http. will be included in the http {} context block
  • Files starting with server. will be included in the server {} context block
  • Files starting with staging. will be included in the staging {} context block
  • Files starting with public. will be included in the public {} context block

Nginx config reloader

On Hypernodes we run a small daemon called the nginx-config-reloader.

This very lightweight Python daemon listens for file changes in /data/web/nginx. If new configuration is added, or the existing configuration is changed, this daemon
picks up on the changes, and copies al files to /etc/nginx/app.

When this is done, the daemon validates the Nginx configuration files for syntax correctness.

If the syntax is ok, the Nginx web service daemon will be reloaded. If the syntax is not ok, the errors will be written to /data/web/nginx/nginx_error_output and the
Nginx service will not be reloaded to avoid crashes due to syntax errors.

This way an incorrect config will not take down your shop when the config reloads, but warns you instead. Additionally you can adjust your Nginx config without the need for root privileges.
A syntax error in your configuration is far from perfect, because when the Hypernode get’s rebooted, the Nginx service will not come up as because of the syntax errors.

Tips:

  • After changing your Nginx configuration, always check for config errors in /data/web/nginx/nginx_error_output
  • Your bash terminal will show a warning if the nginx_error_output file is present in /data/web/nginx
  • If your config is incorrect, fix the errors immediately to avoid a broken configuration on reboot.

Specific configurations

Some typical scenarios are explained below:

More specific Nginx configurations can be found in the category page about Nginx

Do’s and Don’ts

While you can easily extend the Nginx config yourself, there are a few things you need to keep into consideration.
Your Hypernode is designed to host a single Magento installation from the root of its public folder. We don’t advise running non Magento software from the root of your /data/web/public folder, as the core config assumes there’s a Magento there. While you can easily host, say, a (WordPress) blog in a subdirectory, the reverse (With Magento installed into a subfolder) is not supported. You also shouldn’t add subdomains, virtual hosts, or custom server blocks, as these may conflict with future updates, and we advise not to change the server_name setting, as this may break your SSL settings. If you think you do need to change any of these settings, let us know, and we’ll work with you to get it working in a secure way, if possible.

Don’t use includes in your Nginx config in /data/web/nginx as this will break the Nginx config after moving the files to its destination by the nginx-config-reloader daemon.

Modern logging

Instead of using the log format used by Apache, or NCSA webservers, we’ve opted to create our access logs in a powerful JSON format. The advantage of this format is that it makes the logs a lot easier to automatically parse, and a lot easier to expand when we want to add more information to them, without breaking existing tools. And speaking of tools, we’ve included a powerful log analyser on your Hypernode, called hypernode-parse-nginx-log, or pnl for short. For more information, see our article on logfiles.

Converting .htaccess files to Nginx configuration

When moving from a webserver that is running Apache, to a Hypernode, which is running Nginx, some adjustments are required to make sure your shop is functioning.

Where Apache uses .htaccess files per directory to instruct Apache, Nginx does not make use of them. Therefor all configuration in .htaccess files should be converted to Nginx configuration.

Helper tools to convert Apache configuration to Nginx configuration

You can easily convert rewrites and other configuration from your .htaccess file to Nginx config by using a converter tool
These tools are not completely accurate but can convert many statements from your .htaccess to Nginx configuration.

Additionally the Nginx website provides some rules of thumb as well

Find all htaccess files and add denied directories to the Nginx config

To find htaccess files that deny access to custom directories, use the following command:

find /data/web/public -type f -name .htaccess -exec grep -q 'Deny from all' {} \; -exec echo {} \;

This will list all htaccess files that deny access. The ones from the Magento core are already blocked.
The locations that are not in the Magento core, should be denied access to using nginx configuration:

location ~* "(/custom/location|/other/location|/third/custom/location)/?" {
    deny all;
}

0