Automatic Host Routing using NGINX and Vagrant on OS X


Okay, so when I was running a LAMP stack in the early days of development, one of my biggest gripes was creating VHOSTS every time I wanted to test a new framework, or develop a new app etc. I know it’s not a massive chore, but it’s enough of a chore for me to think twice about testing something.

When I moved to NGINX things were pretty much the same – which annoyed me even more. I thought “there must be a better and easier way of doing this!” and there is…

In case you wonder what I mean, it’s basically having the ability to type in an address into my browser and have this routed to a folder on my Vagrant set up – so for example if I type in it’ll use the folder mynewframework in my projects directory as the root. It’s a simple thing but it saves so much time and effort you’ll wonder why you didn’t do it before!

I’ve been running my dev-env this way for a good few years now and it works brilliantly for me so I thought I would share it with others who may find it beneficial.

NB: As usual my caveat in this presumes you have installed Vagrant, you have a working dev-env box up and running with some flavour of NGINX running on it (and probably PHP-FPM) and now you just want to get the automated side of things working. If not, there are a ton of good tutorials out there for installing NGINX and PHP-FPM on CentOS (my OS of choice) so go look-see and come back when you’re running…

Okay, so what are the main things we need to do in order to achieve what we’re after?

We need to:

  • Set up the NGINX configs for the redirect
  • Define a process to override this if needs be (for things like codeigniter etc)
  • Tell OS X how to redirect to the set up we have used for all <whatever>.app domain names (with dnsmasq and resolver files)

This is all relatively straight forward, so let’s start with the custom NGINX config…

In the config folder of your NGINX installation (your installation may differ but mine was in the following… /usr/local/nginx/conf/ ) create a file called auto-redirect.conf – this can be done by simply running the command:

$ vi /usr/local/nginx/conf/auto-redirect.conf

Once this empty file opens, simply add the following to it:

## TO A FOLDER IN /www/<server>/public

server {
    listen 80; ##We must run as root (sudo) to be able to listen on port 80
    server_name app *.app;

    ## This is the bit of code which basically checks if we have entered .app as a hostname
    set $sub 'default';
    if ($host ~ "^(.*).app") {
        set $sub $1;
    error_log /var/log/nginx-error.log debug;
    root /var/www/$sub/public;
    location / {
        index index.php index.phtml index.html index.htm;
        try_files $uri $uri/ /index.php?$query_string;
    location ~ \.php$ {
        try_files $uri =404;
        root /var/www/$sub/public;
        fastcgi_pass; ## Set this to your FPM details
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;


This file basically says “if we have a anything ending in .app, use the first part as a variable, and then use that variable as the home root folder name”. The rest of the stuff is standard NGINX config stuff and you can change it as you see fit.

One thing to note in this config file is as you can see it redirects requests to the /public/index.php file – if you’re using a framework or set up which doesn’t use this structure, you’ll need to add a new config to override the redirect one in order to get these to work. I normally have an ‘overrides.conf‘ file which I load before the redirect file if this is the case which contains the relevant server blocks but details the server specifically:


for example. That way, will be caught by that server block before the redirect one.

Next thing we need to do is tell NGINX to use this file in its main config as the first server block – that way anything else will fall through to any other logic you have running. Edit your main config file by running the following:

$ vi /usr/local/nginx/conf/nginx.conf

Add the following before the first server block in that file, or before any other includes you have which load server blocks (such as sites-enabled etc) but after any overrides you may have specified above.

## Custom auto set up for redirecting nginx to folders :
include auto-redirect.conf;

That should be pretty much it in terms of NGINX now, so you can go ahead and restart if you like and now we need to move on to telling OS X to redirect all requests to .app to our Vagrant box (if you haven’t already)…

Using DNSMASQ to redirect requests…

If you’re not already using dnsmasq to redirect your requests, I strongly suggest you do – it’s fantastic and will save you a lot of ‘$ sudo vi /etc/hosts‘ in the future heh. Rather than go through and tell you everything here, there’s a fantastic post here which shows you everything you need to do to install and use dnsmasq. I suggest you read it and use those methods. The only change I made compared to those was adding the following:

after this line:

add this:

That will redirect all .app requests to Also, under the part about creating the /etc/resolver/<name> file, I created the filename app instead of dev as in the tutorial (/etc/resolver/app). The main reason for these changes is since that tutorial was written, .dev has become a valid TLD and as such you wont be able to access it if you use .dev locally – so better to go for something else, such as .app.

That’s about it really – if all went well you should now be able to add folders to your /var/www/<folder_name>/public/index.php directory and access them by typing in the <foldername>.app in your browser. Hope you find that useful.



3 thoughts on “Automatic Host Routing using NGINX and Vagrant on OS X

  1. Pingback: Creating a Self Signed SSL for Local Development with Vagrant / NGINX – switchcaseblog

  2. Usually with this setup I have ~/projects/ within my home folder and then I symlink it to /var/www.

    $ ln -s /home//projects/ /var/www/

    This is based on my linux setup, but OS X is very similar, you’ll get it with minor adjustments.

    Liked by 1 person

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s