Steps to convert htaccess to NGINX

Are you trying to convert .htaccess rules to NGINX directives?

This guide is for you.

The most notable difference between Apache (.htaccess) and Nginx is in the underlying architecture of the way they handle requests.

Here at Ibmi Media, as part of our Server Management Services, we regularly help our Customers to fix NGINX related configuration.

In this context, we shall look into the process to convert common .htaccess rules to NGINX directives.

The concept of NGINX Rewrite and Return Directives?

The most commonly used directives with NGINX are the return and rewrite directives.

When using an NGINX directive, it can direct a client visiting a page to a different directory or a different landing page. Further, it can also redirect requests to an application depending on the directives we specify.

NGINX Return Directive

It is a best practice to use the return directive over the rewrite directive whenever possible as it is a bit less complicated than the rewrite directive.

We will typically include the return in a server context that specifies the domains to be rewritten. For instance, using the directive in the following format will forward a client that visits www.ibmimediatest.com to www.ibmimedia.com.

server {
listen 80;
server_name www.ibmimediatest.com;
return 301 $scheme://www.ibmimedia$request_uri;

NGINX Rewrite Directive

The rewrite directive is somewhat different than the rewrite rules in .htaccess. We need to place it in a specific location or server block to rewrite the URL.

The rewrite directive is usually used to perform smaller tedious tasks.

For example, it is used in some cases to capture elements in the original URL or change elements in the path. The basic syntax for an NGINX rewrite directive is given below.

rewrite regex URL [flag];

It is important to note that a rewrite directive will almost always return an HTTP 301 or 302 status code. If we need the webserver to return a different status code, the return directive needs to be added after the rewrite.

For example,

rewrite ^(/download/.*)/media/(.*)..*$ $1/mp3/$2.mp3 last;
rewrite ^(/download/.*)/audio/(.*)..*$ $1/mp3/$2.ra last;
return 403;

In this example, the URLs that start with /download followed by /media or /audio are matched. Afterwards, directories /media and /audio elements that contain /mp3 will have the extension .mp3 or .ra file extension added to the URL.

This return directive will return a 403 to the client if the URL does not match the rewrite rule.

How to Convert .htaccess rules to NGINX directives?

Let us see a few examples of commonly used .htaccess rules that we will be converting to NGINX directives.

Redirecting from example.com to www.example.com

Adding the www to a URL when a client requests content from the server can help certain sites to function more efficiently. A common .htaccess rule to accomplish this rewrite is:

RewriteCond %{HTTP_HOST} example.com
RewriteRule (.*)https://www.example.com$1

Below we will be creating a server block within the nginx.conf to accomplish the same task:

server {
listen 80;
server_name example.com;
return 301 http://www.example.com
server {
listen 80'
server_name www.example.com;

We are telling NGINX to listen on port 80 for requests to example.com. Then to return a 301 "redirection" to www.example.com.

We usually split these rules into two server blocks to make these directives as efficient as possible.  We don’t always need the second block but will serve content from the working directory, once it requests www.example.com.

If no exact match is found, NGINX then checks to see if there is a server_name with a starting wildcard that fits. It then selects the longest match beginning with a wildcard to fulfill the request.

Finally, we can test your syntax by running the following command:

$ nginx -t

This allows us to test the syntax for errors before loading the changes in the configuration file.

Once we have edited the NGINX configuration file be sure to restart NGINX using a daemon or simply running the command below.

$ nginx -s reload

Working with WordPress Permalinks?

By default, WordPress includes the following rules to allow it to utilize permalinks on an Apache server:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index.php$ - [L]
RewriteCond ${REQUEST_FILENAME} ~ - f
RewriteCond ${REQUEST_FILENAME} ~ - d
RewriteRule . /index.php [L]

Below is the NGINX equivalent. It does not require any return or rewrite directive here as we are only allowing the content management system to hide the paths using permalinks.

location / {
try_files $uri $uri/ /index.php?$args;

Finally, we can test the syntax by running the following command and then restart NGINX

$ nginx -t
$ nginx -s reload

How to Force http to https?

Another popular use for the .htaccess file is to force the browser to load the site using https over HTTP. This allows the browser to verify the site is not a security risk by confirming the site exists on the server it claims to be on.

The following .htaccess rule will force https so that it redirects the requests using port 80 for example.com to https://www.example.com.

RewriteEngine On
RewriteCond %{HTTP_HOST} ^example.com [NC]
RewriteCond %{SERVER_PORT} 80
RewriteRule ^(.*)$ https://www.example.com/$1 [R,L]

To accomplish this with NGINX, we will use the NGINX return directive.

server {
listen 80;
server_name example.com;
return 301 https://www.example.com$request_uri;

Finally, test the syntax and reload NGINX as we did in the steps earlier.

[Need urgent assistance to convert htaccess to nginx directives? – We are available 24*7]


This tutorial will guide you on how to convert htaccess to nginx directives by keeping the directives within the server block while converting the .htaccess rewrite rules to NGINX rewrite directives.