A Drupal Developer’s Setup on Windows

This page outlines what I’ve done to get a good Drupal dev environment – Apache, MySQL, PHP, Git, Drush and most Linux-style shell commands – running on Windows. There are other solutions out there and I’m always interested in hearing what others have done to optimize their setup. Please leave any suggestions is the comments.

Drush support on Windows is still a little lacking, mostly surrounding commands like drush updatedb (and, thus the database part of drush pm-update) which spawn separate processes that are problematic on Windows. I’m working on getting that fixed, but that make take a while to get sorted out. This setup will give you the basics – download modules, disable/enable modules, etc.

This page DOES NOT go into migrating content from dev/staging servers to live servers. If that’s what you’re lo0king for, sorry. I’ve been to endless DrupalCon BoF’s, Drupal group meetings and numerous online conversations around content migration and there is no real solution except “wait for 8.”

I was lucky (???) enough to have my laptop’s motherboard fail so I was able to refine these steps on a brand-new computer with a clean install of Windows 7. It’s a pretty long process, but you only have to do it once…  Well, once per laptop failure.

Setting up a Drupal Dev Environment

1. Install and configure WAMP Server:
   1. Install WAMP Server using the default settings
   2. Start –> Control Panel –> System and Security –> Administrative Tools –> Services
      1. Double click the wampapache service. Set the Startup type to Automatic (Delayed Start), click the Start button, then OK.
      2. Repeat for the wampmysqld service.
      3. The delayed start option simple puts these services at the end of the list of services started when you computer boots up. If you really need to have your WAMP server running as soon as your computer starts, set the Startup type to Automatic.
   3. To start the WAMP Manager – which gives you easy access to the various WAMP services – automatically on start up, follow these steps. Otherwise you can run it off the Start menu as needed. However you get WAMP Manager started,
      1. Control Panel –> System and Security –> Administrative Tools –> Task Scheduler.
      2. Click Create task… in the right-hand pane.
      3. General tab: name this task and tick the Run with highest privileges checkbox .
      4. Trigger tab: Click New… and set Begin the task to At log on, then click OK.
      5. Actions tab: Click New… and point Program/script to your wampmanager.exe (usually C:\wamp\wampmanager.exe) then click OK.
      6. Conditions tab: (if you’re on a laptop) uncheck Stop if computer switches to battery power, Start the task only if the computer is on AC power and every option in the Idle section. (Oddly, you need to check a parent item in order to uncheck a child item in this dialog…)
      7. Settings tab: uncheck Stop the task if it runs longer than and If the task does not end when requested, force it to stop.
      8. Click OK to create the task and reboot your computer to test it out.
      9. If you want to use Clean URLs, click on the WAMP Manager icon and select Apache –> Apache Modules –> rewrite_modules.
      10. Click on the WAMP Manager icon in the task bar and select Put online .
   4. Decide where your localhost root directory will be. I recommend making this your dev root directory as well, such as C:\dev or C:\Users\<user-name>\Documents\dev. I use the latter option so I can keep all my important files in the same directory. In the following steps, we’ll call this <path_to_root>.
   5. Configure your httpd.conf file: click the WAMP Manager icon in the Taskbar notifications area and select Apache –> httpd.conf. If the system asks, set notepad.exe as the editor for this file type.
      1. Search for the line Include conf/extra/httpd-vhosts.conf and uncomment it (remove the leading ‘#’ character) and save.
      2. Search for DocumentRoot and change the directory to your <path_to_root> directory. The line should look similar to DocumentRoot "C:/Users/mikeker/Documents/dev". If you have spaces in your path name, the quotes are required.
      3. A couple lines below the DocumentRoot location you’ll find:

         # This should be changed to whatever you set DocumentRoot to.
         #
         <directory "c:/wamp/www">

         Do what the man behind the curtain says and change c:/wamp/www to your <path_to_root>.
   6. Setup some convenient shortcuts: I usually put these on my desktop but they can go anywhere that makes sense for you.
      1. The system’s hosts file, which allows you to point certain Web addresses to your WAMP server instead of the Internet: Set the shortcut location to: notepad.exe "<path to hosts file>"  (You need to include the quotes if there are spaces in the path). The hosts file is usually located at C:\Windows\System32\drivers\etc\hosts.
      2. WAMP Server’s virtual hosts config file: notepad.exe "<path to wamp>\bin\apache\<apache-version-number>\conf\extra\httpd-vhosts.conf"  (Again, you need to include the quotes if you have spaces in the path). The virtual hosts config file is usually located at C:\wamp\bin\apache\Apache2.2.17\conf\extra\httpd-vhosts.conf, though the Apache version number can change with new builds of WAMP Server.
      3. Right-click on each shortcut and select Properties. On the Shortcut tab, click Advanced… and check the Run as administrator checkbox.
      4. Double-click on the virtual hosts shortcut, click Yes to the UAC warning, and either delete or comment out the examples that come with the file.
      5. Click the WAMP Manager icon and select Apache –> Service –> Restart Service. If the icon doesn’t return to its green, “all is ok” state pretty quickly, you’ve likely got an error in your httpd.conf file or your httpd-vhosts.conf file. Look at the Apache error log (WAMP Manager: Apache –> Apache error log) for clues.
2. Install PuTTY using the default options:
   1. PuTTY allows you remote access to servers via SSH, as secure way to issue commands on your site’s server from your dev machine. If you do a lot of work on remote server, consider pinning the PuTTY program to the Taskbar.
   2. PuTTY also comes with PuTTYgen which lets you easily create and manage SSH key, which is what Git uses to authenticate a user on a given server. We use it in a bit.
3. Install and configure Git:
   1. Install Git for Windows (follow the Windows link and download the Full installer for official Git x.y.z) using the default settings (I was using version 1.7.4)
   2. Click the Start menu and type git. Click on the Git Bash option then right-click on the Git Bash icon in the Taskbar.
   3. Click Pin this program to the taskbar

   4. Right-click (again) on the Git Bash icon in the Taskbar, right click on the Git Bash item and click on Properties

      1. Shortcut tab: Set the Start in option to your dev root directory, in my case: %HOMEPATH%\Documents\dev
      2. Options tab: set Buffer Size to 900 (or however large you want your scrollbar to go back), ensure Quick Edit is checked.
      3. Layout tab: Set your preferred window size in the Window size and Window position fields, making note of the window width setting – you’ll use that later on.

   5. Go to your drupal.org user account page, click Edit followed by Git access.

   6. Copy the Git user configuration lines and paste into your command shell.  This tells Git how to identify you to drupal.org and other Git servers. If you haven’t already, check the I agree to these terms checkbox in the Git access agreement section

   7. If you haven’t already uploaded an SSH key to drupal.org, switch to the SSH Keys tab and click the Add a public key link.

      1. From the Windows Start menu, type puttygen and select the PuTTygen option that appears. This utility makes it easy to create and manage SSH keys.
      2. Click the Generate button and wiggle your mouse over the blank area as requested to provide some random input.  When the key is generated, add a passphrase to the key and click Save public key then Save private key.  Keep in mind that your public key is only as secure as your private key/passphrase, so use a reasonably complex passphrase and don't put your private key anywhere open to the general public.
      3. Copy the text generated in the large text box at the top of PuTTygen and paste it into the Key field on drupal.org and click Save.
   8. The Git shell install does not include the wget command, which Drush uses to download packages from drupal.org. Download wget from Sourceforge, grab the Complete package, except sources executable and run the installer using the default settings.
4. Install and configure Drush
   1. Go to the Drush Git instructions page and copy the git clone line from the top of the page. git clone is the best way to download code that you want to keep as up-to-date as possible. A simple git pull origin from within that directory will update it to the latest and greatest.
   2. Open a Git shell, navigate to where you want to put Drush (e.g.: cd ~/Documents; mkdir bin; cd bin) and paste the Git clone command.  Note: the key combination Alt+Space e p is the shortcut for paste in a command shell.  Or you can right-click anywhere in the window.
   3. Download this patch for Drush (note: this part is in flux, depending on how that issue is resolved) and apply it. (execute git apply <path_to_patch> from the root of the Drush directory).
   4. If you are unfamiliar with vim, check Google for some quick tutorials or use your favorite text editor.  In your Git shell type vim ~/.bashrc and add the following code and save

      # Drush
      export DRUSH_PHP=/C/wamp/bin/php/php5.3.5/php.exe
      #                 ^-- Replace with your path to php.exe
      export COLUMNS=110
      #              ^-- Replace with the window width noted above
      PATH=~/Documents/bin/drush:"/c/Program Files/GnuWin32/bin":$PATH
      #    ^-- Path to drush and  ^-- Path to the wget install
      export PATH

      (Note: if you have spaces in your path names, you need to enclose the entire path in double-quotes. The colon (:) character separates one entry from the next. The tilde character (~) is also a shortcut to $HOME, which on Windows is usually at c:\Users\<user-name>).
   5. While you’re in the .bashrc file add any alias or other shortcuts you like to have (e.g.: alias ll=’ls -l’)
   6. Exit and restart the shell. Test that your changes have worked – try these lines in your shell:

      wget --version
      drush status

      and make sure you don’t get any errors:

      mikeker@MIKEKER-LAPTOP ~/Documents/dev
      $ wget --version
      SYSTEM_WGETRC = c:/progra~1/wget/etc/wgetrc
      syswgetrc = c:\Program Files\GnuWin32/etc/wgetrc
      GNU Wget 1.11.4
      
      Copyright (C) 2008 Free Software Foundation, Inc.
      License GPLv3+: GNU GPL version 3 or later
      <http: gpl.html licenses www.gnu.org>.
      This is free software: you are free to change and redistribute it.
      There is NO WARRANTY, to the extent permitted by law.
      
      Originally written by Hrvoje Niksic .
      Currently maintained by Micah Cowan .
      
      mikeker@MIKEKER-LAPTOP ~/Documents/dev
      $ drush status
       PHP configuration     :  C:\wamp\bin\php\php5.3.5\php.ini
       Drush version         :  4.5-dev
       Drush configuration   :
       Drush alias files     :

5. Install and configure your favorite code editor, in my case Aptana’s version of Eclipse.
   1. Set Window –> Preferences –> General –> Editors –> Text Editor –> Displayed tab width to 2 and check the Insert spaces for tabs option
   2. Navigate to General –> Editors –> File Associations in the left-hand pane
      1. Click the Add… button next to the File types list (the top Add button) type *.module in the File type text box
      2. Click the Add… button next to the Associated editors list (the bottom Add button), select PHP Source Editor from the list and click OK
      3. Repeat steps 1 and 2 for each of these file types:
         *.engine
         *.inc (may already be associated with the PHP editor)
         *.theme
         *.install
         *.profile
         *.test
   3. When you first start Aptana, you may get a Windows Firewall alert. If so, allow access as you see fit.

Basic workflow for a new project

When I’m starting work on a new site, here’s my basic workflow:

1. If needed, click the WAMP Manager icon, select phpMyAdmin, create a database and user for this project and give the user the needed permission for the new database.
2. Edit the hosts file: Double-click the hosts shortcut created above, click Yes to the UAC warning, and add a line similar to 127.0.0.1  local.example.com to the file and save. I like to preface all localhost addresses with the local subdomain so that it’s easy for me to tell what is live and what is dev. Plus local.example.com will still work with multi-site configurations of Drupal and it’s easy to switch from a given page on the live server to the same page on the dev server (assuming you’ve copied the database recently) by just swapping www for local.
3. Edit httpd-vhosts.conf: Double-click the shortcut created above, click Yes to the UAC warning, and add code similar to:

   <VirtualHost *:80>
       DocumentRoot "<path_to_root>/example.com/drupal-7.0"
       ServerName local.example.com
   </VirtualHost>

   (or whatever the current version of Drupal is) and save the file. (And make sure the example code is removed or commented out as mentioned above).
4. Restart Apache: click the LAMP Manager icon then Apache –> Services –> Restart Service.
5. Open the Git shell and navigate to <path_to_root>/example.com  and type drush dl.
6. Point your browser to local.example.com and the Drupal install screen should come up

You’re ready to rock! Go forth and build amazing Web sites.