A Drupal Developer’s Setup on Windows
UPDATE: 3/23/2013: In general, these instructions still work for Windows 8. While some of the UI aspects have changed, the basic directions are the same. One exception is when downloading PuTTy. Since it’s an unsigned .exe file, Windows will boldly claim that “Windows protected your PC.” Click More info followed by Run anyways and you’re on your way.
UPDATE: 4/22/2012: A few more scattered updates, plus a new section on setting up XDebug on Aptana for super-easy debugger config.
UPDATE: 12/1/2011: Got a new work laptop so I’ve updated these instructions – mostly with regards to Drush (5.x branch has great Windows support) and some optional performance tweaks when setting up MySQL.
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.
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
- Install and configure WAMP Server:
- Install WAMP Server using the default settings. Be sure to pick the 64-bit version if you’re running a 64-bit Windows. If you’ve got more than 4 GB of memory (which you should!) you need to run 64-bit Windows to take advantage of it. If you have a firewall running, you may get an alert about Apache HTTP Server communicating on various networks. If you’re only doing local development (meaning other computers will not need to access your localhost) then you can deny the firewall request.
- Start –> Control Panel –> System and Security –> Administrative Tools –> Services
- Double click the wampapache service. Set the Startup type to Automatic (Delayed Start), click the Start button, then OK.
- Repeat for the wampmysqld service.
- 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.
- 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.
- Control Panel –> System and Security –> Administrative Tools –> Task Scheduler
- Click Create task… in the right-hand pane.
- General tab: name this task, tick the Run with highest privileges checkbox , ensure that Run only when user is logged on is selected, and that Configure for is set to Windows 7.
- Trigger tab: Click New… and set Begin the task to At log on, then click OK.
- Actions tab: Click New… and point Program/script to your wampmanager.exe (usually C:\wamp\wampmanager.exe) then click OK.
- 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…)
- Settings tab: uncheck Stop the task if it runs longer than and If the task does not end when requested, force it to stop.
- Click OK to create the task and reboot your computer to test it out.
- You can force Windows to show the WAMP Manager icon all the time by clicking the little up arrow next to the notifications area, clicking Customize…, and setting Aestan Tray Menu to Show icon and notifications.
- If you want to use Clean URLs, click on the WAMP Manager icon and select Apache –> Apache Modules –> rewrite_module.
- Click on the WAMP Manager icon in the task bar and select Put online .
- Control Panel –> System and Security –> Administrative Tools –> Task Scheduler
- 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>.
- 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.
- Search for the line Include conf/extra/httpd-vhosts.conf and uncomment it (remove the leading ‘#’ character) and save.
- 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.
- 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>.
- If you have plenty of memory in your dev machine (and you should), give MySQL more room to work: in <path to wamp>\bin\mysql\mysql<version-number> rename the existing my.ini to my-original.ini, then rename my-innodb-heavy-4G.ini to my.ini.
- Drupal loads a lot of files and WAMP’s default realpath_cache_size is easily overwhelmed. Click the WAMP Manager icon and select PHP –> php.ini, uncomment (remove the leading semi-colon) the realpath_cache_size = 16K line and bump the number up to 16M or 32M. Save and close php.ini.
- Setup some convenient shortcuts: I usually put these on my desktop but they can go anywhere that makes sense for you.
- 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.
- 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.
- Right-click on each shortcut and select Properties. On the Shortcut tab, click Advanced… and check the Run as administrator checkbox.
- 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.
- Click the WAMP Manager icon and select Stop All Services. Navigate to <path to wamp>\bin\mysql\<mysql-version-number>\data and delete (or rename) ib_logfile0 and ib_logfile1. Click the WAMP Manager icon again and select Start All Services. 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.
- If you have real-time malware detection software you may want to create an exemption for the MySQL data directory (eg: C:\wamp\bin\mysql\mysql5.5.16\data) since files in there will be changing all the time, causing your malware software to run overtime.
- Install PuTTY using the default options (I recommend using the Windows installer option):
- 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.
- 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.
- Install and configure Git:
- Install Git for Windows (follow the Download for Windows link) changing only one of the default settings: On the Configure line endings dialog select Checkout as-is, commit as-is. Unless you’re using a non-*nix aware code editor (possibly Visual Studio?) your it should be able to handle either type of line ending. If you’re unsure, go with the default as this is an option that is easy to change later, or even on a project-by-project basis.
- Click the Start menu and type git. Click on the Git Bash option then right-click on the Git Bash icon in the Taskbar.
- Click Pin this program to the taskbar
Right-click (again) on the Git Bash icon in the Taskbar, right click on the Git Bash item and click on Properties
- Shortcut tab: Set the Start in option to your dev root directory, in my case: %HOMEPATH%\Documents\dev
- Options tab: set Buffer Size to 900 (or however large you want your scrollbar to go back), ensure Quick Edit is checked.
- 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.
- OK the Properties dialog.
Go to your drupal.org user account page, click Edit followed by Git access.
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.
I recommend the settings outlined on Drupal.org for configuring Git. The most important one is setting core.autocrlf and core.safecrlf to false -- that prevents a lot of bogus end-of-line warnings if you use Coder to check your coding standards. Instructions to setup Coder to work with Drush is a little farther down.
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.
- 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.
- 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 accessible to the general public.
- 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.
- Grab a few binaries that Git doesn’t install
- The Git shell install does not include the wget command and uses a piss-poor version of tar, both of which Drush uses extensively. We’ll grab better versions from GnuWin32, an open source collection of Linux shell commands for Windows. Download the wget and libarchive packages, grab the Complete package, except sources executable and run the installer using the default settings (feel free to uncheck the options to create Start menu folders, etc.)
- Navigate to the folder where GnuWin32 installed the binaries, usually similar to C:\Program Files (x86)\GnuWin32\bin, and rename bsdtar.exe to tar.exe.
- Add the bin directory to your path. While we're in here, we'll add a few other paths as well. In your Git shell type vim ~/.bashrc and add the following code and save:
# GnuWin32 tools # Remove the " (x86)" if you're running 32-bit Windows PATH="/C/Program Files (x86)/GnuWin32/bin":$PATH # Support PHP from the command line # Update "php5.3.13" to point to the version of PHP installed PATH=/C/wamp/bin/php/php5.3.13:$PATH # MySQL for the commandline, in particular mysqldump # Update "mysql5.5.24" to point to the version of MySQL installed PATH="/C/wamp/bin/mysql/mysql5.5.24/bin":$PATH # Point Git to the correct SSH client export GIT_SSH="/C/Program Files (x86)/PuTTy/plink.exe" # This should come after any PATH additions export PATHIf you are unfamiliar with vim, check Google for some quick tutorials or use your favorite text editor. 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 (~) can be used as a shortcut to $HOME, which on Windows is usually at c:\Users\<user-name>
. Also note that we have to add the GnuWin32 binaries before the rest of the $PATH variables so that bsdtar, now renamed simply tar, will be found ahead of Git’s tar executable.
- There are plenty of other *nix commands not included with the Git shell (eg: more). If you grab GnuWin32 installers for those commands, they should use the same bin directory.
- Close and reopen your Git shell. Type
wget --versionand check that you don't get any error messages.
- Install and configure Drush – this part got a lot easier after the 12/1/2011 update of this page. (Note: there is a Windows installer for Drush, but I like having more control over where and what is installed. But if you’re not having fun playing around on the command line, it’s a completely acceptable option. Just be sure to unselect the PHP runtime option and skip steps 1 – 4, below).
- Go to the Drush project page, right-click on the tar.gz download option for the latest release of the 5.x branch, and select Copy link address (or whatever option your browser shows for copying a link address). The 5.x branch includes much better support for Windows than previous version of Drush. Kudos to the Drush developers for not treating Windows users as second class citizens!
- In your Git shell: Change directory to wherever you want to install Drush, (e.g.: cd ~/Documents; mkdir bin; cd bin). Type wget <url_of_drush_5.x_download> followed by tar –zxvf <drush-5.x>.tar.gz.
Note: you can right-click on the Git shell to paste, or the keyboard combination of alt+space e p will select Edit –> Paste from the system menu. You can also hit the tab button to autocomplete filenames, meaning you probably only need to type tar –zxvf drush and hit tab to unpack the download.
- In your Git shell type vim ~/.bashrc and add the following code between the GnuWin32 bit and the export $PATH line and save:
# Drush export DRUSH_PHP=/C/wamp/bin/php/php5.3.8/php.exe # ^-- Replace with your path to php.exe export COLUMNS=110 # ^-- Replace with the window width noted above PATH=~/Documents/bin/drush:$PATH # ^-- Replace with your path to Drush
- While you’re in the .bashrc file add any alias or other shortcuts you like to have (e.g.: alias ll=’ls -l’)
- Exit and restart the shell. Type drush status to see if everything is working correctly:
mikeker@MIKEKER-LAPTOP ~/Documents/dev $ drush status PHP configuration : C:\wamp\bin\php\php5.3.8\php.ini Drush version : 5.0-dev Drush configuration : Drush alias files :
- Optional: Install PEAR and DrupalCS to ensure your code adhears to the Drupal Coding Standard.
- Install PEAR
- Download the go-pear.phar script and save it to <path_to_wamp>/bin/php/php<version_number>/go-pear.phar.
- Open a command shell as administrator (Start -> type cmd -> right-click on the cmd.exe option and select Run as administrator), navigate to where you saved go-pear.phar and type php -d phar.require_hash=0 go-pear.phar followed by Enter.
- The script should show you a list of file locations. Hit Enter to accept the defaults and continue.
- PEAR will install and may warn you about the PEAR directory not being in the PATH -- that's fine.
- When prompted, select Y when asked to alter php.ini. Don't close the command prompt, we'll need it in a bit.
- Open Windows Explorer and navigate to your PHP directory. You should find a PEAR_ENV.reg file here. Double-click it to add the PEAR environment variables to your registry.
- At this point you can run PEAR in command prompts (but NOT the Git shell -- .bat files don't play well with the MSysGit shell). Since I don't install PEAR packages more than once every blue moon, that works fine with me. If you do fiddle with PEAR packages regularly, you'll want to include the path to your PHP directory in your Windows path environment variable (as opposed to adding it to your .bashrc as we did earlier).
- Install Code Sniffer and configure it to work with Drush
- Back in the command prompt (not a Git shell), navigate to your PHP directory (eg: c:\wamp\bin\php\php<version_number>).
- Type pear update-channels and hit Enter to ensure you've got the latest and greatest.
- Type pear install PHP_CodeSniffer and hit Enter.
- The following commands will install Coder as a Drush extension, open a Git shell for these. This works fine UNLESS you have coder installed as a module in a project you're working on. My preferred config is to do my code checks with Drush, but if your situation doesn't allow it you can install coder anywhere else that Drush will pick it up on a project-by-project basis. See the Drush README Commands section for details.
cd ~ # Check if .drush exists, if not # mkdir .drush cd .drush drush dl coder
- Back in the command prompt with administrative permissions, navigate to your PHP directory (eg: c:\wamp\bin\php\php<version_number>) followed by \pear\PHP\CodeSniffer\Standards. From here type mklink /j Drupal %HOMEPATH%\.drush\coder\coder_sniffer\Drupal and hit Enter. If you placed coder someone other than your ~/.drush folder, you'll need to replace the second argument with the appropriate path.
- Test it out by opening a Git shell (we should be done with command prompts for now...), navigating to a Drupal install and typing drush dcs index.php. Note: if you're working in a Git repository, you'll get errors regarding invalid end-of-line characters and files not ending with a single newline. That's because Git converts Unix line endings to Windows when you checkout files.
- Install PEAR
- Install and configure your favorite code editor, in my case
Aptana’s version of EclipseSublime Text 2. (Note Eclipse/Aptana config instructions have been moved). My ST2 configuration is a work-in-progress.
You’re ready to rock! Go forth and build amazing Web sites.
Basic workflow for a new project
When I’m starting work on a new site, here’s my basic workflow:
- 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.
- 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.
- 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).
- Restart Apache: click the LAMP Manager icon then Apache –> Services –> Restart Service.
- Open the Git shell and navigate to <path_to_root>/example.com and type drush dl.
- Point your browser to local.example.com and the Drupal install screen should come up