Nginx redirects are used to point one URL or domain to another.

There are two main types of redirects:

  1. Permanent Redirects (301 Moved Permanently): These inform the browser that the old address has permanently moved to a new location. For example, if you change the domain name or URL structure of your website, then you would permanently redirect users using this method.
  2. Temporary Redirects (302 Found): These are useful when a URL needs to be served from a different location temporarily. For instance, during site maintenance, you might redirect visitors to an explanation page.

Different Ways to Create Redirects in Nginx

To implement redirects in Nginx, you can use either the built-in rewrite directive or the return directive. Let’s take a look at each of them.

return Directive

The return directive is a straightforward way to perform URL redirections. You can simply use the return statement to specify a status code (from the 3xx series) and the target URL. For example, the following code will issue a permanent (301) redirect to the specified URL:

return 301 https://example.com$request_uri;

It’s recommended to use return when you don’t need to validate the URL with a regex expression or capture elements from the original URL. This method is simpler and faster because NGINX stops processing the request immediately after encountering it.

rewrite Directive

The rewrite directive is more flexible than the return directive, but it’s also more complex as it provides you with the flexibility to manipulate URLs using regular expressions.

For example, if you moved a whole bunch of resources from one path to another, then instead of creating a separate redirect for each of them, you can use a regular expression to capture parts of the original URL and use them in the new URL.

For instance, the following snippet will match anything after /old-path/ and appends it to /new-page/:

rewrite ^/old-path/(.*)$ /new-page/$1 permanent;

However, note that the rewrite directive can only create 301 (permanent) or 302 (temporary) redirects. If you need other status codes (such as 303 or 307), you’ll have to use the return directive.

Setting up Custom Nginx Redirects

RunCloud makes it easy to add and remove custom Nginx configurations on your server for each of your web applications. You can use this functionality to create Nginx redirects as well (without ever needing to log in to your server via SSH).

To get started, log in to your RunCloud dashboard and then navigate to the “NGINX Config” section of the web application where you want to add a custom redirect.

On this screen, click on “Add a New Config” to create your configuration, and select “I want to write my own config” from the drop-down menu. Under the type section, select “location.main-before” and provide a descriptive name for this configuration.

Creating Temporary Nginx Redirects

After completing the above steps, you can add your custom configuration in the given text box to start redirecting traffic.

To create a temporary redirect using the return directive, use the following code snippet:

location = /old/runcloud {
  return 302 /new/runcloud;
}

In the above example, don’t forget to replace the /old/runcloud with the URL that you want to redirect traffic from, and the /new/runcloud with the URL of the webpage where you want to send your users.

Similarly, to create a temporary redirect using the rewrite directive, you can use the following code snippet (and replace the values using the method described above):

rewrite /old/runcloud /new/runcloud redirect;

Creating Permanent Nginx Redirects

The process needed to create a permanent redirect is very similar to creating a temporary redirect – you only need to change a small part of the config to make it permanent.

If you’re using the return directive, all you need to do is replace 302 with 301 – that’s it. Let’s take a look at the previous example from the temporary redirects section:

location = /old/runcloud {
  return 301 /new/runcloud;
}

In the above snippet, we can see that the Nginx server will return the new URL with HTTP status code 301, which will tell visitors that it is a permanent redirection.

Similarly, for a rewrite directive, you need to replace redirect with permanent and you’re all set! For example:

rewrite /old/runcloud /new/runcloud permanent;

Note: You can either add multiple redirect rules in the same configuration file or create multiple files, as per your preference. We recommend creating a separate file each for temporary and permanent redirects to avoid confusion.

Once you have added all necessary rules, click on the “Run and Debug” button to check your file for syntax errors. If you get a ‘Success’ message, then you can click the “Save” button to publish your changes to the live site.

Once you save the changes, RunCloud will automatically modify your server settings accordingly, and reload your server with the new configuration. If you want to modify your redirect configuration, you can do so by clicking on its name on the Nginx Config page in the RunCloud dashboard.

Domain1 to Domain2 Redirect Rule Nginx (retain path)

Let’s say you’ve just migrated a website from domain1.com to domain2.com – you’d obviously want to map 1:1 redirects so that all pages on domain1.com point to their new versions on domain2.com.

This is really simple to do with an Nginx redirect rule.

Simply place the following redirect rule into a web application that has domain1.com mapped to it (this can be a custom PHP web app that is otherwise empty and only used for the purpose of the redirect). 

 rewrite ^/(.*)$ http://domain2.com/$1 permanent;

All requests would be redirected to domain2.com, retaining the path of the original request, i.e., domain1.com/path would redirect to domain2.com/path, etc.).