CakePHP is a framework that allows for rapid PHP development. I recently installed it on one of my home test servers and there were a few steps specific to an Ubuntu install that were required but that were not clearly outlined in the official documentation.

The version of the Apache web server that gets installed via the package manager in Ubuntu (I prefer apt-get personally) compartmentalizes many of the Apache configuration files, so rather than editing a single httpd.conf file, we unfortunately have to hunt and peck for individual configuration files and modify them as needed.

This install guide begins immediately after a base install of Ubuntu has been completed. It takes us through installing the fundamentals, and ends with a working install of CakePHP, ready for development work. It assumes our server is dedicated to a single CakePHP-based website. Since this is an internal, home-based test server setup, I don’t put as much emphasis on securing the server, so bear that in mind as you work through this. You or your organization may have some additional security measures to take after getting CakePHP up and running.

Phase I: Basics

Assuming we’ve just completed a base install of Ubuntu (Server or Desktop, it doesn’t really matter) with a static IP or reservation via DHCP, we now have a few basic packages to install. They are:

• Apache: our web server. This is important. Without it, nothing else will work.
• PHP 5: another foundational piece of software. Without PHP installed, CakePHP won’t work.
• MySQL: our database management client and engine.
• Vim: our text editor.
• Git: the tool we use to copy (or clone) CakePHP from github.com.
• OpenSSH Server: for convenient remote shell access.

Note: MySQL and OpenSSH Server are not used in this tutorial, but they’re good to have installed. The reality is, eventually you might need a database for your CakePHP-based website, and at some point, you’re probably going to want secure access to your web server from a remote terminal.

To install the aforementioned packages, all we need to do is access our terminal and type:

regularuser@smalleycreative:~$ sudo apt-get install apache2 php5 php5-mysql mysql-server vim git openssh-server

During the install, we’re asked what we want our MySQL root password to be. We can set it to whatever we want, and make a note of it for later. Please resist the urge to sticky it to your monitor.

Now is a good time to do a quick restart of the Apache service, in case it doesn’t see that PHP is present. If Apache can’t see PHP, PHP can’t be used, and if PHP can’t be used, then CakePHP won’t work. To restart Apache, we type:

regularuser@smalleycreative:~$ sudo service apache2 restart

Phase II: Acquire Cake

First, some background information: There are two official ways of getting and working with CakePHP. We can either manually download CakePHP and copy it into our web root (this is where we store our websites on a web server. On Ubuntu this is located at /var/www), or we can use git to clone CakePHP from github.com into /var/www.

Note: Git is a tool that we use for something called version control or revision control. Put very simply, version control is a concept that allows developers to maintain different versions of their code in a more organized fashion. It provides a level of protection against errors and allows for a more robust method of managing changes to a code base. That’s all you need to know for the purpose of this guide. We are going to clone CakePHP from github.org. This downloads a copy (or clone, get it?) of the CakePHP code repository to a directory of our choosing on our server. Also, an added bonus is that no decompression is needed.

We can do this completely from the Ubuntu terminal by typing:

regularuser@smalleycreative:~$ cd /var/www
regularuser@smalleycreative:~$ sudo git clone https://github.com/cakephp/cakephp.git

Within a few seconds, the most current version of the CakePHP code should be downloaded from github.com to our /var/www directory. Cool, huh?

Phase III: Configuration

The final step in getting CakePHP up and running is to make a few configuration changes to our server. The first thing we need to do is modify permissions on tmp, a directory in the CakePHP source code repository that should now be located at /var/www/cakephp/app/tmp. More specifically, we need to ensure that this directory and all directories within it are writable by the web server user. A quick and dirty way to do this is:

regularuser@smalleycreative:~$ sudo chmod 0777 -R /var/www/cakephp/app/tmp

Once that is out of the way, we need to modify a configuration file located at /etc/apache2/sites-available/default. Most tutorials on how to install CakePHP tell us to modify our httpd.conf file, but in our case, we’re not interested in httpd.conf, we’re interested in /etc/apache2/sites-available/default. As I stated earlier, Apache under Ubuntu is set up a bit differently, and configuration files are more compartmentalized. There are two main changes we need to make to our default file. To make these changes, we can open default in vim by typing:

regularuser@smalleycreative:~$ sudo vim /etc/apache2/sites-available/default

Once in vim, we need to modify two lines in our default configuration file. First, we modify something called our DocumentRoot. The DocumentRoot is the directory where our main URL redirects. By default, it points to /var/www. CakePHP documentation states that our DocumentRoot must point to /var/www/cakephp/app/webroot. To achieve this:

DocumentRoot /var/www

should be changed to

DocumentRoot /var/www/cakephp/app/webroot

Before we continue, a brief explanation is required. In Apache, a file called .htaccess can be placed in any website. Unsurprisingly, the original purpose of the .htaccess file was access control, but now it controls a lot more than just access. In our case, CakePHP uses .htaccess to rewrite and shorten what would otherwise be long, complex URLs. Most servers have a master (or global) .htaccess file, and many have individual (or local) .htaccess files located in individual directories in the /var/www directory tree that control access on a per website basis. This allows for more a more fine-grained configuration on servers that run more than one website, and though it takes a little bit more work, having multiple .htaccess files is the preferred method of configuration because of the level of control it affords the server administrator. Before Apache will allow local .htaccess files to take precedence over the global .htaccess file, a configuration setting called AllowOverride must be changed. This setting is located in our default configuration file as well. We need to change AllowOverride from None to All. This instructs Apache to allow local .htaccess files to override the global .htaccess file. To do this:

       <Directory />
               Options FollowSymLinks
               AllowOverride None
       </Directory>

must be changed to

       <Directory />
               Options FollowSymLinks
               AllowOverride All
       </Directory>

Once this change is made, we’re done with the default file, so we can save and quit vim using :wq.

Now that our configuration file is set up, we need to enable mod_rewrite. mod_rewrite is the Apache module that allows Apache to shorten URLs. Apache will not allow this behavior by default, it’s something we need to explicitly configure. Whenever we hear someone say, “Enable mod_rewrite”, what they’re telling us is to turn on this module so that Apache can make changes to URLs. To do this, we type:

regularuser@smalleycreative:~$ sudo a2enmod rewrite

And we get some output telling us mod_rewrite is being enabled and that we should restart Apache to apply the change:

Enabling module rewrite.
Run '/etc/init.d/apache2 restart' to activate new configuration!

We finish our configuration phase with a restart of Apache to apply all of the configuration changes we’ve made:

regularuser@smalleycreative:~$ sudo service apache2 restart

Phase IV: Test!

To test, we open a web browser and type in the IP address or hostname of our server in the URL bar. Assuming everything is properly set up, we should see a CakePHP template page complete with CSS styling and a few small images. There may be some notices or warnings on this page, but we should still be in good shape to begin development using CakePHP.