CakePHP 2.x running on Cherokee webserver

Its no secret that Apache is bloated, or that there are many decent replacements. Cherokee is one of them and a good one at that. I have been running Cherokee for a couple of years now without any issues, for both personal and client applications. One of the things that drew me to Cherokee was the GUI admin interface. GUI's may not be to every ones taste, but it beats sifting through config files every day of the week.

And here is a snip of the (not to pretty) config file:

server!bind!1!port = 1234

# The proxy configuration
vserver!1!nick = default
vserver!1!document_root = /tmp
vserver!1!rule!1!match = default
vserver!1!rule!1!handler = proxy
vserver!1!rule!1!handler!header_hide!1 = server
vserver!1!rule!1!handler!balancer = round_robin
vserver!1!rule!1!handler!balancer!source!1 = 1

# URL rewrite
vserver!1!rule!1!handler!rewrite_request!1!regex = ^/(.+).png$
vserver!1!rule!1!handler!rewrite_request!1!substring = /$1.jpg
vserver!1!rule!1!handler!rewrite_request!2!regex = ^/test/(.+)$ /$1.jpg
vserver!1!rule!1!handler!rewrite_request!2!substring = /test.php?$1

# The information source
source!1!type = host
source!1!host = localhost:9090

So you want to give Cherokee a run for its money? This is how to get CakePHP up and running.

Install

As is the case with smaller projects and linux, the apt-get repos are never up to date. The latest version available (as of writing this) is 1.2.101 while the apt-get repos contain 1.2.1 or something similar. You should either compile from source (it has no dependencies) or add the ppa. I choose to use the ppa as its a bit easier to do and I don't need to look up the commands.

I use php-fpm with Cherokee which has served me well. I have also used fcgi in the past and a few other options for php but php-fpm seems to do a good job and never had much issues with it. It also did not require any custom start up scripts that were required for some of the other options out there. You can install this with sudo apt-get install php-fpm if you do not have something installed already.

Once you have installed Cherokee you should be able to access the admin interface by running sudo cherokee-admin from the terminal. If you have installed on a cloud or VPS server you can add the -b param to get it working from the outside. Without the -b option Cherokee will only be accessible at http://localhost:9090, with -b you can access http://your-site.com:9090

Preparation

Much like Apache, Cherokee has vHosts but they are called vServers. These allow setting up multiple domains on a single server. Besides being much easier to manage through the GUI, you can also make use of something called dynamic vServers which allow you to configure one vServer that will work for many domains. I tend to use this option most of the time as it means there is much less administration required as new sites are configured or adjusted.

To create a vServer the webroot files need to exist (except for the dynamic vServers). If this is not a localhost install you probably want to configure your DNS so that the configuration can be tested.

vServers

I will start of with a more simple example of a single domain matching a single webroot. Open up the GUI (http://site.tld:9090), once there click the vServer button at the top of the page (roughly centred on the screen). You should have something similar to the following with the single default vServer already configured. If you navigated to the site at this point you should see the default Cherokee file listing.

Start by adding a new vServer, this is the small + sign at the top left of the page just above the default vServer. A box will appear with some options for a quick configuration. Clicking on the language tab should give you a PHP option. Using this preset will automatically create a few of the config options required for PHP, such as the php-fpm script and so on.

Once you selected the PHP option, run through the wizard. It will ask for a couple of things such as the webroot path and the hostname. Once complete it will create the new vServer and return to the listing. You should see a few more options now.

So you now have a basic PHP configuration working, but need a few more changes to make CakePHP work. The most obvious one is making CakePHP rewrite rules work with Cherokee. The other thing that needs to be done is making sure that Cherokee handles the sites assets and they are not requested through Cake. Here is what you should have and where you need to get to. Above is the default PHP configuration, below is the target CakePHP configuration. (Ignore the isSSL rule)

The main configurations to change are under the behaviors tab on the vServer config. This is where you are able to add rules and set how requests are handled.

Behavior Rules

Behavior rules allow you to control how requests are handled. You can for example do things like redirect all port 80 traffic to port 443 or block specific a specific IP address or subnet. I will only cover the basics of what is required to get Cake up and running, there is plenty information in the Cherokee docs and some helpful people on the IRC channel (#cherokee on freenode).

Besides the rules to decide how requests are handled you can also configure how content is cached, authentication and a number of other options. These are generally the same for each rule you create and are also covered by the docs on Cherokees site.

PHP

The default configuration for PHP should work out the box without needing any changes. You can look through the options and adjust them as you like.

File exists

This is the rule that handles assets. So long as the asset files are web accessible and you use the direct path to the assets on your site this is the rule that will be used. For example you include an image on your site as http://example.tld/img/my-pic.png, which is located on the server at APP/webroot/img/my-pic.png.

As for other rules you can configure how the assets are cached. If you using time stamped urls for your asset files and its a production site, you will most likely want to set the cache to expire in 2020 or there about. For development you should set cache as already expired to avoid any issues.

Default

This rule has been changed from what the wizard created into a redirect rule. It will handle anything that has not been handled already and rewrite the request accordingly. The rule required for CakePHP 2.3 and onwards is as follows:

Type

Internal

Regex

^/([^\?]*)(\?(.+))?$

Substitution

index.php

The CakePHP redirect rules shown here are good for 2.3 onwards. They might need a bit of modification for earlier versions such as 2.2 or 2.1. This rule should also work fine for urls with normal query parameters such as requests to http://example.tld/users/login?something=foo&bar=1

Request Flow

When a page is requested from Cherokee it will try the first vServer in the list for a match and continue running down the list until a match is found. If none are found it will finally end on the default rule which by default is a directory listing.

Behavior rules work in much the same way. Cherokee starts at the top of the list and works down until the request is handled. This is important as it means the order of the rules is important. The basic flow for each request goes something like this:

Asset files

• User requests a page on your site that includes images.
• The browser requests a file http://example.tld/img/my-pic.png
• Cherokee takes the path img/my-pic.png and checks if the file exists in the webroot directory
• If it exists, it returns the data. If not, Cherokee will continue with the next rule

Redirect

Redirect is the last rule, so if this rule is hit that means nothing else was able to process the request. What about PHP I hear you ask, well when using Cake there are no PHP extensions. Say the user has requested your site at http://example.tld/users/login, Cherokee can not possibly know this is a php request so we rewrite the rule.

The rule has taken everything after the .tld part of the url and rewritten the request to index.php.... When the rewrite happens Cherokee starts the processing back at the top (which is the PHP rule) and will now match as the url is now http://example.com/index.php?/users/login.

If for some reason you had rewritten the request to an image file (that existed) the PHP rule would once again be skipped and the asset one would be used.

PHP

The PHP rule is slightly more complex that the other ones as with this one, cherokee is passing the request information to something that knows what PHP is, in this cake php-fpm. The php-fpm process will handle execute the PHP which in turn renders your output (the login form this time round) and then returns the generated output back to the Cherokee process.

If you have selected to cache PHP content, at this point Cherokee will stick the response into memory. Later requests to the same page will not be passed to php-fpm, but instead taken directly from memory. In any event Cherokee will finally return the content and the request is done.

Save

At this point you should have the various options configured and be ready to run. Cherokee, unlike Apache, does not need a hard restart when changes are made. Click the save button on the top right of the screen and you will be given some options.

Do not restart

This will save your changes but they will not be applied to the server. It will be as if the configs have not yet been edited.

Graceful restart

This is the normal option to use. A graceful restart will not interrupt requests. For example you have a used downloading a 200MB file and you hit graceful restart. That users connection will continue while any new connections are handled using the new configuration, including the next request the download user makes. This is the same restart that is required when cherokee is updated which means you could theoretically have 100% uptime, even through a server update.

Hard restart

This is the typical restart that Apache does. Any existing connection will be dropped and everything restarts.

Your site should now be up and running. If after clicking the save button and you do not get the popup the server may be stopped. If you navigate the GUI back to the home page it will display the status. This usually happens when a configuration option is incorrect and the server is unable to run. Click on start and make note of any errors. If there are none your config will have been applied already, but if there are you will need to address the error as described on screen.

Advanced Hosting

The configuration for advanced virtual hosting is the same in regards to how content is handled and the PHP configurations. The main difference is how domains are matched and where the content comes from.

If you are able to use some sort of convention in your server setup, advanced hosting can save a whole lot of time. I for example keep sites in /var/www/{domain.tld}/public_html. This makes it easy as advanced hosting allows using placeholders on the webroot. There are a number of different placeholders, the configuration looks like the following:

With this setup you will normally only need a couple of vServers to manage endless domains. I personally use one for CakePHP sites, one for generic PHP sites and then add a few custom ones as required. Sometimes I will have a vServer for redirecting no SSL traffic to the SSL port or blocking some shady IP ranges. But 9 / 10 times I do not need to edit any configuration when adding a new domain.