Install mod_cfml to NGINX (any OS)

Based on some great work by Pete Freitag here, and some additions by the mod_cfml team, mod_cfml now has full nginx support!


Make sure you are using the latest mod_cfml.jar, at least version 1.1.05. See the installation instructions for the Tomcat valve.

Background info: the 1.1.05 mod_cfml.jar supports the $document_root as value for the X-WebServer-Context header, which is especially important for Windows users. They will otherwise end up with only one Tomcat host with the Windows drive letter ("C", "D", "E", etc.), since Tomcat will strip anything after the colon (E:\sites\\ would become "E").

Webserver setup - Ubuntu with Lucee

The simplest way to go about it, if you are hosting on Ubuntu, is by using the "ubuntu-nginx-lucee" install scripts from Pete Freitag / Foundeo. It sets up Tomcat, nginx, Lucee, and mod_cfml, all at once.

Webserver setup - general

Here, we assume you already have a webserver setup with nginx on any OS, and you just want to add mod_cfml support, and optionally still need to add proxy support to Lucee/Railo/OBD.

In the files underneath, "lucee" is mentioned. You can also use Railo (and probably Open Blue Dragon) with these settings.

You will need to copy 2 files to your nginx config folder. This is the folder which contains the main "nginx.conf" file, and is by default located at /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx. For Windows, it is the conf directory within the nginx main directory, eg. C:\nginx\conf\
The 2 files to copy are:

You might want to change some of the settings in these files, specifically:

  • In lucee.conf, change "allow;" to whatever matches the IPs you want to have access to the Lucee administrator.
  • If you're using Railo, change "location ~* /lucee/ {" to "location ~* /railo-context/ {" in lucee.conf.
  • In lucee-proxy.conf, you might only want to keep the lines underneath "#add headers for mod_cfml to do its work", if you already have a proxy setup for Lucee.
  • In lucee-proxy.conf, you will need to remove/comment the line "proxy_set_header https $cgi_https;", if you have not used the full Ubuntu with Lucee setup. Otherwise, an error is thrown for the undefined variable $cgi_https.

Now, you will need to add some lines in each nginx server block, which you want to have mod_cfml support for.
A 'server block' is most often configured in either nginx.conf or {nginx directory}/sites-available/*.conf, and looks like this:

server {
  listen 80;
  root /web/;

In each server block, you will need to add the following lines:

set $lucee_context "[a UNIQUE ID for this server block, eg. the server_name value]";
include lucee.conf;

Which makes the server block look like this:

server {
   listen 80; 
   root /web/; 
   set $lucee_context "";
   include lucee.conf;

After you have edited the server blocks, you need to check if the config does not contain any errors. You can do this from the command-line:

$> nginx -t
# Or on Windows:
# $> C:\nginx\nginx.exe -t

# if you're getting an error like "bind() to failed", use:
# $> sudo nginx -t

If everything seems good, restart or reload nginx, and you should be good to go!

More info on the $lucee_context variable

Setting the $lucee_context variable is in most nginx setups optional. Beacuse by default, the document-root will be used as a unique ID.
But it is required to set, if:

  • you are using an 'alias' in ANY server block, for example:
server {
   location /demo {
   alias /path/to/alias/folder;
  • you have multiple server blocks with the same 'root' value.

Make sure you give the $lucee_context variable a unique value. It cannot have the same value in multiple server blocks.
Otherwise, multiple sites will share the same Lucee context!