If you find this post useful, please consider donating in the form of a
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: The 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 — important 🙂
- PHP 5: without PHP, there’s just Cake, which is pretty good on its own, but we want CakePHP.
- 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. It can be whatever we want. Ah, the possibilities…
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: Get CakePHP
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 to
git is a tool that we use for something called version control or revision control. Put very simply, revision 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 codebase. For the purposes of this guide, we can leave it at that. What we’re going to do is clone CakePHP from github.org. This downloads a copy (or clone, get it?) of CakePHP to a directory of our choosing on our server. Also, an added bonus is that no extraction (or unzipping) 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 CakePHP should copy (or clone) down 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 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
vim by typing:
regularuser@smalleycreative:~$ sudo vim /etc/apache2/sites-available/default
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 do this:
should be changed to
Before we continue, a brief explanation is required. In Apache, a file called .htaccess can be placed in any website. The original purpose of .htaccess was access control, but now .htaccess 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 site, and though it represents a little bit more work, having multiple .htaccess files is a 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 must be changed. This is the AllowOverride setting, and it is located in our
default configuration file as well. We need to change AllowOverride from
All. This instructs Apache to allow local .htaccess files to override the global .htaccess file. To do this:
<Directory /> Options FollowSymLinks AllowOverride None </Directory>
needs to 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
Now that our configuration file is set up, we need to enable
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 enable. 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: Testing
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.