URL rewriting is a completely optional feature of Wheels, and all it does is get rid of the index.cfm part of the URL.

For example, with no URL rewriting, a URL in your application could look like this:

http://localhost/index.cfm/blog/new

After turning on URL rewriting, it would look like this:

http://localhost/blog/new

Combine this with the routing functionality of Wheels, and you get the capability of creating some really human-friendly (easier to remember, say over the phone, etc.) and search engine friendly (easier to crawl, higher PageRank, etc.) URLs.

Once you have added the rewrite rules (usually in either .htaccess, web.config or urlrewrite.xml), Wheels will try and determine if your web server is capable of rewriting URLs and turn it on for you automatically. Depending on what web server you have and what folder you run Wheels from, you may need to tweak things a little though. Follow these instructions below for details on how to set up your web server and customize the rewrite rules when necessary.

For webserver specific instructions look at the following pages:

• Apache

• IIS

• Tomcat

• Nginx

Don't Forget to Restart

If you need to make changes to get URL rewriting to work, it's important to remember to always restart the web server and the ColdFusion server to make sure the changes are picked up by Wheels.

If you don't have access to restart services on your server, you can issue a reload=true request. It's often enough.

Instructions for Apache

On most Apache setups, you don't have to do anything at all to get URL rewriting to work. Just use the following .htaccess file and Apache will pick up and use them automatically on server start-up.

There are some exceptions though...

If you have installed Apache yourself you may need to turn on the rewrite module and/or change the security settings before URL rewriting will work:

• Check that the Apache rewrite_module has been loaded by ensuring there are no pound signs before the line that says LoadModule rewrite_module modules/mod_rewrite.so in the httpd.conf file.

• Make sure that Apache has permission to load the rewrite rules from the .htaccess file. This is done by setting AllowOverride to All under the Directory section corresponding to the website you plan on using Wheels on (still inside the httpd.conf file).

If you have an older version of Apache and you're trying to run your Wheels site in a sub folder of an existing site you may need to hard code the name of this folder in your rewrite rules.

• Change the last line of the .htaccess file to the following: RewriteRule ^(.*)$ /sub_folder_name_goes_here/rewrite.cfm/$1 [L]. Don't forget to change sub_folder_name_goes_here to the actual folder name first of course.

Options +FollowSymLinks
RewriteEngine On
RewriteCond %{REQUEST_URI} ^.*/index.cfm/(.*)$ [NC]
RewriteRule ^.*/index.cfm/(.*)$ ./rewrite.cfm/$1 [NS,L]
RewriteCond %{REQUEST_URI} !^.*/(flex2gateway|jrunscripts|cfide|cf_scripts|cfformgateway|cffileservlet|lucee|files|images|javascripts|miscellaneous|stylesheets|wheels/public/assets|robots.txt|favicon.ico|sitemap.xml|rewrite.cfm)($|/.*$) [NC]
RewriteRule ^(.*)$ ./rewrite.cfm/$1 [NS,L]

Note that it's often considered better practice to include this URL rewriting configuration at the <virtualhost> block level, but get it working with a .htaccess file first.

Instructions for IIS 7

Similar to Apache, IIS 7 will pick up the rewrite rules from a file located in the Wheels installation. In the case of IIS 7, the rules are picked up by adding the following web.config file.

This requires that the URL Rewrite Module is installed. It's an IIS extension from Microsoft that you can download for free.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="ColdFusion on Wheels URL Rewriting" enabled="true">
                    <match url="^(.*)$" ignoreCase="true" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{SCRIPT_NAME}" negate="true" pattern="^/(flex2gateway|jrunscripts|cf_scripts|cfide|CFFileServlet|cfformgateway|lucee|files|images|javascripts|miscellaneous|stylesheets|wheels/public/assets|robots.txt|favicon.ico|sitemap.xml|rewrite.cfm)($|/.*$)" />
                    </conditions>
                    <action type="Rewrite" url="/rewrite.cfm/{R:1}" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

Instructions for IIS 6

Unfortunately, there is no built-in URL rewriting mechanism in IIS 6, so getting Wheels working with pretty URLs is a little more complicated than with Apache and IIS 7 (which often comes with the official "URL Rewrite Module" installed by default). Here's what you need to do:

• Download Ionic's ISAPI Rewrite Filter. NOTE: the version must be v1.2.16 or later.

• Unzip the file, get the IsapiRewrite4.dll file from the lib folder and put it in the root of your website. (It needs to be in the same folder as the IsapiRewrite4.ini file.)

• To enable the rewrite filter in IIS 6, click on Properties for your website, then go to the ISAPI Filters tab and click the Add... button.

• Type in anything you want as the Filter Name and point the Executable to the IsapiRewrite4.dll file.

• Uncomment the rewrite rules in the IsapiRewrite4.ini file.

NOTE: Make sure you have "Verify that file exists" disabled for your site.

• Right click your website and select Properties.

• Click Home Directory tab.

• Click the Configuration button.

• Under the Wildcard application mapping section, double-click path for the jrun_iis6_wildcard.dll.

• Uncheck Verify that file exists.

• Click OK until all property screens are closed.

Using rewrite Valve

Tomcat 8 can be configured using RewriteValve. See http://tonyjunkes.com/blog/a-brief-look-at-the-rewrite-valve-in-tomcat-8/ for examples.

Instructions for UrlRewriteFilter

UrlRewriteFilter (commonly referred to as Tuckey) is a Java web filter for compliant web application servers such as Tomcat, Jetty, Resin and JBoss. Unfortunately UrlRewriteFilter depends on XML with its extremely strict syntax.

• First follow the (install instructions on the UrlRewriteFilter website).

• Append the servlet-mapping markup to the end of the <filter mapping> element in your WEB-INF/web.xml

• Add the pretty urls rule markup to the <urlrewrite> element to your WEB-INF/urlrewrite.xml configuration.

• Restart the web application server.

Servlet-Mapping markup

<servlet-mapping>
  <servlet-name>CFMLServlet</servlet-name>
    <url-pattern>/rewrite.cfm/*</url-pattern>
</servlet-mapping>

Example markup with UrlRewriteFilter and Wheels pretty URLs for WEB-INF/web.xml.

<filter>
    <filter-name>UrlRewriteFilter</filter-name>
    <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>UrlRewriteFilter</filter-name>
    <url-pattern>/*</url-pattern>
    <dispatcher>REQUEST</dispatcher>
    <dispatcher>FORWARD</dispatcher>
</filter-mapping>
<servlet-mapping>
  <servlet-name>CFMLServlet</servlet-name>
    <url-pattern>/rewrite.cfm/*</url-pattern>
</servlet-mapping>

Pretty URLs Rule markup

<rule enabled="true">
    <name>CFWheels pretty URLs</name>
    <condition type="request-uri" operator="notequal">^/(flex2gateway|jrunscripts|cfide|cf_scripts|cfformgateway|cffileservlet|lucee|files|images|javascripts|miscellaneous|stylesheets|wheels/public/assets|robots.txt|favicon.ico|sitemap.xml|rewrite.cfm)</condition>
    <from>^/(.*)$</from>
    <to type="passthrough">/rewrite.cfm/$1</to>
  </rule>

A complete barebones WEB-INF/urlrewrite.xml configuration example with pretty URLs.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite
    PUBLIC "-//tuckey.org//DTD UrlRewrite 4.0//EN"
    "http://www.tuckey.org/res/dtds/urlrewrite4.0.dtd">

<urlrewrite>
  <rule enabled="true">
    <name>CFWheels pretty URLs</name>
    <condition type="request-uri" operator="notequal">^/(flex2gateway|jrunscripts|cfide|cf_scripts|cfformgateway|cffileservlet|lucee|files|images|javascripts|miscellaneous|stylesheets|wheels/public/assets|robots.txt|favicon.ico|sitemap.xml|rewrite.cfm)</condition>
    <from>^/(.*)$</from>
    <to type="passthrough">/rewrite.cfm/$1</to>
  </rule>
</urlrewrite>

Example Nginx configuration

# nginx configuration 
location ~ .*/(flex2gateway|jrunscripts|cfide|cf_scripts|cfformgateway|cffileservlet|railo-context|lucee|files|images|javascripts|miscellaneous|stylesheets|robots.txt|favicon.ico|sitemap.xml|rewrite.cfm)($|/.*$) { }

location / {
rewrite ^(.*)$ https://YOURDOMAIN.com/$1 redirect; 
rewrite ^/.*/index.cfm/(.*)$ /rewrite.cfm/$1 break; 
rewrite ^(.*)$ /rewrite.cfm/$1 break; 
}