Setting Up A Local Drupal Development Environment

Soon, well eventually, the blog is going to get a refresh - and we are currently building that refresh in Drupal, which is an open source CMS. To that end, getting Drupal setup on my machine wasn't particularly a hard procedure, but is slightly complex if you aren't used to setting up a local server and database. So if you fall under that category than this tutorial is for you. First you must know that this tutorial is aimed for Windows users and Drupal 6.X. Some basic Linux and Mac OS instructions can be found in the references section of the page.

We are going to start by installing a local server using XAMPP which takes care of handling Apache, Mysql, PHP, and various other development tools. You can download it here. Once it is downloaded run the installer. The first option when installing is the installation folder which defaults to C:\xampp, at least on Vista, which is just fine. The second screen is a set of options, which include a desktop icon (which I never choose), a start menu folder, and a couple of Windows service options. The screenshot below shows these settings. The only thing left to do is click the install button.

Now we get to handle a few items which will make Drupal happy and our lives easier. The first is setting up our Apache install to handle virtual hosts. This will allow us to put our Drupal wherever we want on our computer and will also allow us to give it a nice short domain name such as sotc.local. XAMPP stores the virtual host file, httpd-vhost.conf, at C:\xampp\apache\conf\extra. Now open this file with Notepad - I prefer Notepad++ - and we are going to add some configuration information to it. The following piece needs to be added to the end of the file. This will enable virtual hosting for 127.0.0.1 on port 80 and setup the default host. The default host is where your browser will go if you type in localhost or 127.0.0.1 and this is set by being the first virtual host in the file.

Setting up a Virtual Host

Next we need to add the virtual host entry for our site. This is going to look similar to the one above except we are going to change the name and add a few more options. The first thing we will notice in the below host entry is in the opening tag where we get the domain name we are going to use. This can be anything as we are going to add it to our Windows host file - well it shouldn't be anything that will conflict with an existing Internet site. The DocumentRoot is where we are going setup our site and is the root directory. The ServerName is the same domain we put in the VirtualHost tag. Next we add an option to keep log information and provide a place to store them. One item to note is that the directories already need to exist. Apache will not create the directory. It will only create the log file, also the CustomLog and ErrorLog need to have be on single line each, see comment from kudrixa for more details. Lastly we have the directory options, which defines the directory, which is again pointed to our root, and adds particular options for it. These options are necessary but would take a lot to explain them fully so I will point you to Apache's documentation instead.

This completes our virtual host, leaving us with a file like the one below. I have cut out some of the comments for shortness sake.

Now we need to tell our computer that we have setup another host on our machine. This can be done by modifying the host file. You can find this file at C:\WINDOWS\system32\drivers\etc\hosts and again I opened it with Notepad++. Inside this file I added a new entry for my local setup which looks like the following:

Now when I type sotc.local in the browser my local Apache server will show me the web content at C:\........\Drupal Local. Now my windows host file will look like the below, again I taken out some of the comments to shorten it.

Enabling mod_rewrite

The next item we are going to take care of is adding the ability for clean urls, these are nice looking urls (like the one currently being used on this blog) instead of bad nondescript urls - for instance http://blog.paranoidferret.com/?p=25. In order to have this feature in Drupal we need to enable the Apache module, mod_rewrite, which allows Apache to do some url magic. You can learn more about this magic here.
So in order to get this done we need to edit the Apache configuration file, also known as httpd.conf. You can get this file at C:\xampp\apache\conf\httpd.conf as long as you installed XAMPP to C:\xampp\. Break out notepad again and open the file. We need to find the following line (search works well here):

Once you have found it take out the pound sign (#) which will uncomment the line of code. This line will now read:

Okay, next we restart Apache which can be done using the XAMPP control panel. You can open the control panel by clicking the orange X symbol in your task tray. From the control panel you can also modify your XAMPP install. Now just stop and start Apache. The control panel will look something like the below picture.

Setting up Drupal Database

One of the nice things about XAMPP is that it automatically adds phpMyAdmin (a simple way to administer MySQL) to our local server when installed. This will give us easy access to our MySQL install and allow us to add a database for Drupal. Drupal requires a database to be created before you install it. You should be able to go your phpMyAdmin install by clicking this link. You should see something very similar to the following image.

Next we add the database, this is very simple - just type the name into the "Create new database" text input. Now just press the "Create" button to the right of the text input and viola we have our database. Picture reference below.

Installing Drupal

The final task for this tutorial is getting Drupal installed correctly. The first step in this process is downloading it from here. Downloading... downloading... downloading... done. Okay, next we extract the contents of the first folder in the .tar into our local root. So in my case my Drupal Local folder looks like:

Now open up a browser window and go to your local domain that we created earlier - in my case sotc.local. This will start the installation process. First we choose a language:

The second screen we get to is the database setup screen. We have already done all the leg work here in creating our database. So in the "Database name" box we will put drupalDB (unless you named yours differently) and in the "Database user" box we put root. By default there is no password for our local server, and this is fine since only your local machine can access it. Just click the continue button and lets keep moving. NOTE: I do not recommend using the root user or blank passwords in production environments.

The next section is for configuring our Drupal install. The first part is the site name and site email address - you can choose whatever you like here. Next we have to put in the user information for the administrator account. I personally use very simple things here for ease of testing and development. For the username I always choose admin and the same for the password. Also don't forget to drop an email address here. The last small piece is for time zone settings and clean urls, this is what we setup mod_rewrite for. You should see a message that says the server was successfully tested for these. Finally you can decide whether to check for auto updates. Click "Save and Continue" and everything will finish up.

If all has gone well you will now have a clean local install of Drupal 6.1. I have noticed every now and then that the install process will hang after clicking the continue button on the last screen. I always let it run but open a new tab in my browser and go to sotc.local to see if it has finished. After a couple minutes most likely you will get a page like the very first image in this tutorial. Now just have some fun and get to setting up your CMS. All questions, concerns, and complaints are always welcome.