Mapping domains in WordPress Multi User with Nginx

It turns out that adding domain mapping support to WordPress MU using Nginx isn’t too hard (caveat ahoy: assuming that you have WordPress Multi User set up already and general familiarity with Nginx that is!).

This is how I got it to work with some additional tweaks to help save a little time when mapping more domains.

You will require:

  • One VPS set up with your chosen flavour of Linux, Nginx and PHP
  • A working WordPress MU installation
  • A domain that you want to map to a sub site in MU

Changing domain provider settings

Before you even touch your site you need to change the nameserver and IP settings to point to your new domain to a web server that hosts MU. Allow up to 24 hours for the DNS settings to propagate.

A good domain provider allows you to do all this via a dashboard. I use LCN which has a really easy to use admin back end (LCN are very good too btw).

Add the domain to your VPS’s DNS settings

Your VPS provider should have a domain management area where you can add a domain zone for new URLs.

My Linode VPS host adds default settings automatically which seems to work for me (e.g. www and mail prefixes are created in the A/AAA records).

Create a new site

Of course you can’t map a domain if you don’t have a site to point it to, so you need to create a new sub site from within MU.

I have my WordPress MU install set up to create sites as subdomains (e.g. I don’t know if this is critical but I thought it might be worth mentioning.

Obviously you can map your domain to pre-existing sub sites too.

If you haven’t done so already you will need to install the WordPress MU Domain Mapping plugin which is the special sauce that helps to tie all of this together.

Map the domain using the domain mapping plugin

Once you have the new site up and running you need to map the new domain in your site admin.

You can do this from the Dashboard at the Network Admin end via Settings > Domains but I recommend going to the admin area for the new site and adding it via Tools > Domain Mapping.

This allows you to set the subdomain as primary so you can at least access the new site while you wait for the domain to propagate. You will need to go back and set the mapped domain as primary once  it has propagated and all the configurations have been made.

Nginx configuration

Nginx is a lightweight and quick web server. Apache is perhaps more common for most WordPress set ups. Nginx is sometimes used in conjunction with Apache to serve up static files. If that is your set up then this tutorial isn’t for you. See the_guv’s notes below about how to do this if you are using Nginx as a reverse proxy with Apache.

A typical Nginx set up will have several config files pulled in as includes by the main nginx.conf.

Nginx will request your vhost file via a symlink in a directory called sites-enabled. The main vhost file is kept in the sites-available directory.

Here’s the path for my set up: /usr/local/nginx where sub directories labelled conf, sites-enabled and so on are kept. If you don’t find Nginx there then it will most likely be in etc/nginx

My nginx.conf looks like this.

Note the includes (highlighted).

Skipping include mime.types we’ll concentrate on:

include /usr/local/nginx/sites-enabled/*

Note the wild card “*”. This tells Nginx to return any symlink in the directory that matches the requested domain.

sites-enabled contains all the symlinks that point to corresponding vhost files in sites-available

Create a new configuration file

Open your console and login as root user (note: a secure server set up will not allow you to log in directly as root. If yours does then you need to do something about it!).

Create a new folder within your Nginx directory and call it domains then create a new file inside this directory and call it multi_domains (all will become clear! You could of course give this directory and file names that are meaningful to you):

mkdir domainstouch domains/multi_domains

Open the new file for editing:

nano usr/local/nginx/domains/multi_domains

And add your new domain:

Important: make sure that there are no gaps before or after this line. The “.” at the start of the domain makes sure that both and are available.

Now save your newly edited file.

Delete the symlink in sites-enabled

You are going to edit your vhost file so delete the vhost file symlink in sites-enabled that corresponds to the main domain for your multisite (e.g. – using my earlier example):

rm sites-enabled/

Edit your vhost file in sites-available

Now open the original multisite vhost file  in the sites-available directory.

The vhost file looks like something like this:

Note the line:

In the example I linked to at the very start of this tutorial the recommendation is to simply add your domain as a new line below this one e.g.:

Now this is fine but presumably you will want to map other domains to your multisite later on. This means deleting the symlink, editing the vhost file, setting up a new symlink then restarting Nginx.

Not hard but now you have your domain in an external file you can remove a couple of steps. Instead edit your vhost like this:

Now save the edited vhost file and set up a new symlink:

ln -s /usr/local/nginx/sites-available/ /usr/local/nginx/sites-enabled/

Now restart Nginx:
/etc/init.d/nginx stop/etc/init.d/nginx start

If your domain has already propagated you should be able to visit your sub site at If not wait it out and try again later.

If you made primary when you added the new domain in your WordPress dashboard then you will need to go back and make the new domain primary instead.

Adding additional domains to your configuration

Now you have a shortcut. In future all you have to do is add new domains to multi_domains e.g.:

And that’s it – no need to delete the symlink, edit the vhost and create a new symlink. Just restart Nginx:
/etc/init.d/nginx stop/etc/init.d/nginx start

Happy multisite hosting!

3 thoughts on “Mapping domains in WordPress Multi User with Nginx

  1. nice job Perry 🙂

    one addendum … for those using Nginx as a reverse proxy, follow this tut as is and, in the Apache vhost for, change the line:-


    … to …

    ServerAlias *

    And in the vhost for the newsite, the new sub-domain, ensure the DocumentRoot directive points to the html dir, so something like:-

    DocumentRoot /home/USERNAME/public_html/

    And reboot the web servers:-

    apache2ctl restart && service nginx restart

    (I guess you could shortcut the Apache process for adding a new sub-domain, similarly to what Perry’s done here, as an alternative, but I’m old and crusty and haven’t tried.)

    PS … what’s your syntax highlighter? … very nice.

    1. Cheers Olly – and I really should say that I couldn’t have got anywhere near as far as this without the tutorials by your good self at 😉

      The syntax highlighter is a relatively new one – you can do useful things like highlight specific lines of code and so on:

      Crayon Syntax Highlighter

      I’m not sure how it handles long lines of code yet (obvs I’ve chosen to make this page as wide as possible and the conf lines are quite short).

Leave a Reply