User Tools

Site Tools


running_backlight_2_on_nginx_web_server

Running Backlight 2 on Nginx Web Server

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:

  1. Configuring Nginx to protect data and cart purchase directories
  2. 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;

# 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/([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;

        # 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/([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:

  1. Copy or rename the file backlight/env.php.skel to backlight/env.php on your server
  2. 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);
running_backlight_2_on_nginx_web_server.txt · Last modified: 2019/07/11 04:53 by ben