Advanced Config Guide: NGINX-Only Mode on Pagely VPS

Last Updated -

This article is part of our Advanced Configuration Series. We will guide you through some of the more advanced web server capabilities of your Pagely VPS. We assume you are comfortable with using SSH command line and have a familiarity with NGINX configuration files. If you're ever unsure or need assistance getting something running under NGINX-only mode, our Support Team is just a few clicks away!

As outlined in our Guide to NGINX+Apache and NGINX-only modes, you have the option to make your site run without Apache and have NGINX interface directly with your PHP FPM workers. This feature unlocks a lot of possibilities for web server configuration and also boosts performance. 

Before You Switch

Consider Testing On a Staging Site First.

Often times, our customers will start with creating a staging site to test things out there first. This is especially important if you have existing .htaccess rules to convert to NGINX configuration format. 

.htaccess Rules

When a site is in NGINX-only mode, the .htaccess rules for your site will not be processed. If you have anything beyond the basic WordPress rules, you will want to have the rules converted to NGINX format before making the jump.

This is an example of a default .htaccess WordPress ruleset. If this is all you have, you can switch without further work as our default NGINX-only mode already handles this default case:

# BEGIN WordPress

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

# END WordPress

If you have any other rules, such a redirects for forcing SSL or taking care of old links, we strongly recommend working on a staging copy of the site first. Our Support Team can assist with this cloning and conversion process.

Changing a Site to NGINX-Only Mode

It's very simple to switch your site to use NGINX-only mode! You can do this from within Atomic. It works on a per-site basis.

Changes are applied within a few seconds with little to no downtime (maybe a few seconds for uncached requests).

Switching back is easy too!

Available Flex-Points

Once an app is enabled for NGINX-only mode, you have access to place configuration files in one of two available flex-points. This will be the equivalent of .htaccess rules in NGINX land. Depending on what you are attempting to do, the files would go in slightly different paths.

Each app has a special path under /data/s#####/dom#####/user/ where you can create the flex-point directories. If it's your first time using NGINX-only mode for a site, you can create the directory first:

  1. Switch to the user directory within your site (replacing s##### and dom##### with your site's path):
    cd /data/s#####/dom#####/user/
  2. Create the nginx-server directory:
    mkdir nginx-server
  3. Create the nginx-http directory:
    mkdir nginx-http

Next, we'll cover what each folder is for!

/nginx-server/ Folder

This is the most used flex-point, it is included within the context of the main server {} block for the app so you can have config files as simple as a single line rewrite or rules specific to a location. All of these rules are processed before the main location / {} block.

Appropriate rules to place within nginx-server pertain to rewrite, location {}, allow, deny, if, anything that can reside inside of the context of a server {} block. 

As a simple example, here is a redirect rule in .htaccess format:

Redirect 301 /some/old/article/

The equivalent in NGINX would be:

rewrite /some/old/article/ /some/new/article/ permanent;

If you are doing a 302 instead of a 301, simply replace permanent with redirect.

And the file would go in /data/s#####/dom#####/user/nginx-server/custom-redirects.conf

/nginx-http/ Folder

The nginx-http flex-point allows placing rules outside of the standard server{} block entirely. This is very rarely ever needed and has a higher chance of causing unintended side effects, including causing all sites to be unavailable or serve the wrong content. While it is available to use, we strongly recommend contacting our Support Team before placing any rules under nginx-http so that we can help review the code and test it out in our own lab beforehand. Common uses for this flex-point include map, server, limit_req_zone, and other things that must reside outside of or within their own server{} block.

Applying Your New Rules

Now that you've got your config files in place, you have to apply the rules. Pagely's Support Team can do this for you, or you may request access to pagely-nginx command line tool to manage this yourself.

Sudo Access to pagely-nginx

You may file a support ticket to have us enable you for sudo access to run the pagely-nginx script. This will allow you to test your configuration file for syntax, reload the service, and start it up again if bad rules keeping NGINX from starting up manage to be applied by accident.

Once enabled for this option, you can run:

  • sudo pagely-nginx configtest : tests all included configs for syntax
  • sudo pagely-nginx reload : reloads the service, applying the new rules immediately
  • sudo pagely-nginx start : starts up the the service if bad rules manage to crash the server (requires fixing the bad rules first)

You can also work with our Support Team to have us reload nginx service for you.

Connection Limits

NGINX-only mode configures a hard clamp on how many dynamic requests can be made at the same time. This is a self-stabilizing feature which is designed to briefly turn traffic away if the PHP FPM worker pool for your app is full of slow requests. Cached pages will still serve during these situations, and static assets are not affected by this limit. This manifests as 503 Service Unavailable responses.

This limit automatically scales up as you upgrade your plan to higher resource levels and it also automatically starts letting new requests through as soon as the slots starts to free up. With that said, this is the most common noticeable change in server behavior when switching to NGINX-only mode.

If you experience frequent 503 errors after switching to NGINX-only mode, these are most likely issues that were happening under the normal NGINX+Apache mode. We recommend switching back to the standard mode right away and contact us for further assistance. In NGINX+Apache mode, instead of fast 503s you would be seeing long waiting times for requests to complete.

Make sure to review our Optimization Guide next!

Redirecting All Old Blog Posts

The following rule is specifically for for redirecting old /YYYY/MM/$name permalinks to new /$name permalinks:

rewrite ^/blog/([0-9]+)/([0-9]+)/(.*)$ /blog/$3 permanent;

Related Topics

Pagely is the Managed WordPress Hosting Platform designed to exceed the needs of media, business, and Enterprise customers alike. We help the world's biggest brands scale WordPress.

Copyright © 2006-2017 Pagely, Inc. All rights reserved.
Pagely® and WordPress® are registered trademarks.

Powered by Zendesk