Running on Nginx

The Turning Gate fully supports Backlight on Apache servers running on Linux.

Some customers prefer to host on other web servers, such as IIS and Nginx. While Backlight should work in those environments, we do not have the resources to fully test Backlight in environments beyond Apache/Linux. As such, any support is provided on a best-effort basis.

Backlight should run on Nginx web servers with no modification to the code itself. It is essential that the site be configured properly on the web server, in particular to protect data files and digital purchases from direct downloads.

Configuration of Nginx to run PHP, and general site configuration is beyond the scope of this page.

Setting up Backlight on Nginx is performed in two steps:

Configuring Nginx to protect data and cart purchase directories
Optionally, configure Backlight to use Clean URLs for Page and image links

Configuring Nginx#

Below are entries to be added to your Nginx server configuration for Backlight compatibility. These assume that your site is running at the root, and not in a subdirectory, e.g. at http://yoursite.com/

# Protect against direct downloads of data files.  It is ESSENTIAL to have this rule in place.
location /backlight/data/ {
  return 404;
}

# Protect against direct downloads of digital purchases
rewrite ^(.*)/(.*)/photos-for-purchase/* / last;

# Single Image pages
rewrite ^(.*)/(.*)-single.php $1/single.php?id=$2&mod_rewrite=on last;

# Album RSS Feed
rewrite ^(.*/.*)/feed\/?$ $1/feed.php?mod_rewrite=on last;

# Search
rewrite /backlight/search/ /backlight/index.php?m=publisher&c=gallery&a=search&mod_rewrite=on last;

rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&a=$3&p1=$4&p2=$5&p3=$6&htline=1&mod_rewrite=on last;
rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&a=$3&p1=$4&p2=$5&htline=2&mod_rewrite=on last;
rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&a=$3&p1=$4&htline=3&mod_rewrite=on last;
rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&a=$3&htline=4&mod_rewrite=on last;
rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&htline=5&mod_rewrite=on last;
rewrite ^/backlight/(api)/([a-zA-Z0-9_\-\.]+)\/?$ /backlight/index.php?&m=$1&c=$2&htline=5&mod_rewrite=on last;
rewrite ^/backlight/([a-zA-Z_\-]+)\/?$ /backlight/index.php?m=$1&htline=6&mod_rewrite=on last;
rewrite ^/backlight/$ /backlight/index.php?htline=7&mod_rewrite=on last;

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

  if (-f $request_filename) {
    break;
  }
  if (-d $request_filename) {
    break;
  }

  # Clean URLs for Pages
  rewrite ^/([a-zA-Z][a-zA-Z0-9\_\-]*)(\/|\.html)?$ /index.php?page=$1&mod_rewrite=on last;
}

Below is a complete server configuration for a website that incorporates the above additions. This assumes that Backlight is running directly under the top-level of your site. Change the settings for the server name, website paths and location of log files to be specific to your hosting environment.

server {
  listen 80;
  server_name youriste.com;

  access_log /var/log/nginx/yoursite.log;
  error_log  /var/log/nginx/yoursite.log error;

  root /home/yourdirectory/public_html/yoursite.com;
  index index.php index.html;

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

    if (-f $request_filename) {
        break;
    }
    if (-d $request_filename) {
        break;
    }

    # Pages
    rewrite ^/([a-zA-Z][a-zA-Z0-9\_\-]*)(\/|\.html)?$ /index.php?page=$1&mod_rewrite=on last;

    # Attempt to load dynamic resources if file doesn't exist
    rewrite ^([^\/.]*)\.(css|js|gif|png|jpg)$ /index.php?extension=$2&name=$1 last;
  }

  location ~ \.php {
    fastcgi_index index.php;
      #fastcgi_pass unix:/var/run/php-fpm.socket;
      fastcgi_pass 127.0.0.1:9000;

    include fastcgi_params;
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
  }

  # Prevents caching of css/less/js/images, only use this in development
  location ~* \.(css|less|js|jpg|png|gif)$ {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Pragma "no-cache";
    expires 0;
  }

  # Protect against direct downloads of data files.  It is ESSENTIAL to have this rule in place.
  location /backlight/data/ {
          return 404;
  }

  # Protect against direct downloads of digital purchases
  rewrite ^(.*)/(.*)/photos-for-purchase/* / last;

  # Single Image pages
  rewrite ^(.*)/(.*)-single.php $1/single.php?id=$2&mod_rewrite=on last;

  # Album RSS Feed
  rewrite ^(.*/.*)/feed\/?$ $1/feed.php?mod_rewrite=on last;

  # Search
  rewrite /backlight/search/ /backlight/index.php?m=publisher&c=gallery&a=search&mod_rewrite=on last;

  rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&a=$3&p1=$4&p2=$5&p3=$6&htline=1&mod_rewrite=on last;
  rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&a=$3&p1=$4&p2=$5&htline=2&mod_rewrite=on last;
  rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&a=$3&p1=$4&htline=3&mod_rewrite=on last;
  rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&a=$3&htline=4&mod_rewrite=on last;
  rewrite ^/backlight/([a-zA-Z_\-]+)/([a-zA-Z0-9_\-]+)\/?$ /backlight/index.php?m=$1&c=$2&htline=5&mod_rewrite=on last;
  rewrite ^/backlight/(api)/([a-zA-Z0-9_\-\.]+)\/?$ /backlight/index.php?&m=$1&c=$2&htline=5&mod_rewrite=on last;
  rewrite ^/backlight/([a-zA-Z_\-]+)\/?$ /backlight/index.php?m=$1&htline=6&mod_rewrite=on last;
  rewrite ^/backlight/$ /backlight/index.php?htline=7&mod_rewrite=on last;
}

Configuring Backlight to support Clean URLs#

Backlight 2 is able to automatically detect that clean URLs should be used on Nginx installations. If your Backlight 2 site is not using clean URLs, then this can be forced with the following change.

To force generation of clean URLs:

Copy or rename the file backlight/env.php.skel to backlight/env.php on your server
Uncomment the setting for FORCE_CLEAN_URLS near the end of that file by removing the leading //, so that the line reads:

define('FORCE_CLEAN_URLS', true);