Wordpress

NginX works perfectly well with a wide variety of applications, and Wordpress is certainly one of them. NginX's configuration language is very powerful and straightforward if one is familiar with it, but often people coming from other servers are not sure how things work in NginX and just copy and paste whatever they see from a blog that seems to fill their needs. Everyone, especially people new to NginX, should check out the nginx.org documentation for an overview of how things work and should be done in NginX.

Abridged basic setup

Hopefully you have read the documentation above and maybe worked on setting up a virtual server or two in NginX already - if not there are a few notes below, but you should still read the documentation. The initial configuration is valid for all versions of nginx except for the fastcgi.conf include which is only in 0.8.30 and on (but there is an alternative fastcgi configuration at the bottom of this section). Unless otherwise specified all configurations are valid for 0.7.x and above.

First we setup a named upstream for our php, which allows us to abstract the backend and easily change the port or add more backends. After that, we setup our virtual host on blog.my-totally-awesome-site.tld!

upstream myphp {
  server 127.0.0.1:9000;
}
 
server {
  listen 80;
  server_name blog.my-totally-awesome-site.tld;
  root /var/www/mysite;
  index index.php;
 
  location / {
  }
 
  location ~ \.php$ {
    include fastcgi.conf;
    fastcgi_pass myphp;
  }
}

With this base configuration we should be able to serve wordpress in its basic state with default permanent links using query strings such as "/?p=1". This is of course provided that the root path, which points to where you will be running wordpress from (it might be in your home directory in a www or public_html folder on a shared box, for example), is correctly specified and that fastcgi is running on the address and port listed in the server value of the myphp upstream. Refer to your error log when in doubt and check out nginx debugging.

Pre-0.8.30 fastcgi settings

If you are using versions of nginx prior to 0.8.30 you will not have the fastcgi.conf file, so you will need to use the following PHP location.

  location ~ \.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass myphp;
  }

Alternatively, you can just add the SCRIPT_FILENAME parameter to your fastcgi_params (better yet, a copy of it in fastcgi.conf) and remove the line from the location.

Location Strategies

There are many ways to declare your locations in your configuration that allow you to do basically whatever you want with your URLs. Usually, people want to have "pretty" URLs that hide the query strings and script files. Here are a few different strategies based on different goals. Here we are defining locations that should be used to replace the basic locations above in order to achieve the desired results.

Basic try_files to URL redirect

This block replaces the block with the blank line in the root location, also known as /,

location / {
  try_files $uri $uri/ /index.php?q=$uri&$args;
}

Non-root try_files to URL redirect

This is essentially the same as the basic version but the location declaration and final try_files parameter are changed slightly to reflect where wordpress is installed.

location /wordpress {
  try_files $uri $uri/ /wordpress/index.php?q=$uri&$args;
}

Basic try_files to internal location

The root location below replaces the root location in the base, and the @internal location is a new addition (not replacing anything).

location / {
  try_files $uri $uri/ @wordpress;
}
 
location @wordpress {
  include fastcgi_params;
  fastcgi_param SCRIPT_FILENAME $document_root/index.php;
  fastcgi_param QUERY_STRING q=$uri&$args;
  fastcgi_pass my_php;
}

Here we've added an internal location called @wordpress that is hard-coded to always use /index.php and passes along the proper query string.

Non-root try_files to internal location

Same as above but with a slight tweak!

location /wordpress {
  try_files $uri $uri/ @wordpress;
}
 
location @wordpress {
  include fastcgi_params;
  fastcgi_param SCRIPT_FILENAME $document_root/wordpress/index.php;
  fastcgi_param QUERY_STRING q=$uri&$args;
  fastcgi_pass my_php;
}

Non-root path-split try_files to internal location

Same as the above, but now we are using fastcgi_path_info to pass along the correct PATH_INFO which wordpress can be configured to use. [todo: test]

location /wordpress {
  try_files $uri $uri/ @wordpress;
}
 
location @wordpress {
  include fastcgi_params;
  fastcgi_split_path_info ^(/wordpress)(/.*)$;
  fastcgi_param SCRIPT_FILENAME $document_root/wordpress/index.php;
  fastcgi_param PATH_INFO $fastcgi_path_info;
  fastcgi_param QUERY_STRING q=$uri&$args;
  fastcgi_pass my_php;
}