Building out a Drupal 6 site

A few tips for those starting out... there's a lot to do when building a new Drupal site! Here are some techniques I use, so I end up doing things in a consistent way.

Sorry if a lot of this is going to sound like mumbo-jumbo; I'm assuming you're familiar with some simple Unix commands, general development tools, and a bit about Drupal. If you see something you don't understand, a quick look on Drupal will probably clear it up for you. These are techniques I've found useful, but may not match your preferences, so feel free to adapt them to your likings. If you're new to Drupal, much of what I'm outlining is considered to be best practices (or at least pretty good ones), and I hope they will help you figure out some good deployment tools.

1) Create a repository

I like to this as a first step, because we are going to need somewhere to put our files anyway, and putting them under version control is more than a good idea. I personally like Subversion, and a lot of folks are starting to use Git, as Drupal moves in that direction. I wouldn't recommend CVS, which takes more work to use. I host my repositories at sourcerepo.com; you can also do it all on your local machine, but having them remotely at a host that takes care of backups and security is a good thing, too.

Create your repository, check it out on your local, and add a few subdirectories for important files. I use theses:

• docs - documentation (extremely important)
• backups - database dumps; a repository isn't the best place for these, since they don't lend themselves to diffs, but I do like to keep a few recent SQL exports tied to milestones, in case I even need to backtrack.
• public_html - the document root of your site

2) Documentation

Nobody likes to write things down, but the only things worse is not having things written down. So start filling up that docs directory. Start with a server.txt file, where you will record the URL, passwords, database connection info, etc. for each host you set up.

Also create a layout.txt, where you will make notes about your design and theming, measurements, colors, etc. I then create additional files to document special feature and other design considerations.

3) Servers

Being as it's risky to work on a live production server, I like to create a local server for initial deployment. Once it is working, I create a remote server to show the site to the client, then a production server for the final site. If the site's domain is myserver.com, these servers would be called local.myserver.com, stage.myserver.com, and www.myserver.com, respectively. Note that the first remote server we set up will become a staging server.

Once the site is up, I can test new code and features on my local, then push it to the staging server for review, and finally push it to the production server.

The secret to all this wizardry is multihosting, which I wrote a little article about recently. This may be a little tricky to figure out the first time, but will quickly become second nature, and save you tons of grief. Almost all professional developers use a variant of this method.

4) The code and contribs

The next step is getting the base code and contrib modules you'll use to build out your site. You can do this the hard way by downloading tarballs and extracting them, but there's a far easier and more accurate method: using drush make. If you haven't discovered this great tool yet, you'll probably kick yourself after you start using it.

To do so, you'll need a Unix-style command line, like the terminal app in Mac OS. If you're using Windows, the stock command line tool just won't cut it; install a Unix emulator like cygwin.

I've attached a sample make file; download it and rename it to myproject.make (or what ever your project is named). Edit it, because it includes everything but the kitchen sink. If there are some unfamiliar modules in there, check them out; you may find some good ways fo doing things.

A few modules that I consider indispensable for development that you might want to leave in are admin_menu, adminrole, module_filter, and devel.

Now go to a scratch directory and issue the command

drush make MYPROJECT.make MYPROJECT

using the name of your project in place of MYPROJECT. You'll find a complete hierarchy of directories and files under the MYPROJECT folder; copy them all to your public_html directory. Of course, you could make public_html the target and not have to do any copying, but I like keeping the original build around for reference until I have everything working.

5) Set up the database and settings

Create your local database. Also create a sites/default/files directory, this will be your base files directory for all your servers.

Once you have your code in place, go to your local URL and run it the first time, and it will fill in your database.

Now let's set up some more settings files. Drupal is going to search first for a directory that matches the URL you are on, and revert to sites/default/settings.php only if it doesn't find a match. Create a sites/local.myproject.com directory (using the correct URL for your local, of course), and copy sites/default/settings.php there. Do the same for sites/stage.myproject.com and www.myproject.com; then go in and edit the settings.php file and set the $db_url variable to match the connection settings for each of your servers (your local is already correct). You will probably need to set the file permission to read/write first, so you can save them.

6) Customizations

I usually create a custom module for a project, where I can put custom blocks, form_alter hooks, and other features.

I also usually make a custom theme. If you're new to theming, I'd recommend trying the versatile Zen theme, or the grid-based Fusion theme and associated Skinr module.

But however you do it, never have a custom module with the same name as your theme! This leads to some pretty ugly and difficult to debug naming conflicts.

7) Check it back in

Now that you are up and running check all your new files back into your repository. The adventure now begins; no matter how bad you mess something up, you can simply delete it and check it back out from your repo.

8) Debugging

One of the great advantages of a local dev environment is how easy it can be to debug code. My favorite tool right now, but unfortunately Windows only, is the phpEd IDE ($209, and worth every cent). Also very powerful, and cross-platform (Mac/Windows/Linuix) is the PhpStorm IDE. There are also some free Open Source debuggers, but they don't shine like these professional tools do. You will save a tremendous amount of time developing custom themes and modules with them, and gain a greater understanding of how contribs work (and sometimes don't work). A good debugger is also a great way to learn how Drupal works internally, and how the great module developers and themers do their magic.

9) Deployment to other servers

Syncing your code to your staging and production servers is a snap; simply check out the repository on the target machine.

Databases are a little trickier; initially, I use phpmyadmin or mysql from the command line to make a complete dump of my database (telling it to drop existing tables on the import), and then import it to the remote hosst. You can also do this in a single step with a tool like Navicat.

Where we run into trouble is when we have our production site running - you probably don't want to keep importing from your local's database, lest you lose any content added to the live site, like comments. Unfortunately, there is no easy automatic way to do a two-way sync. I generally do a dump of the live site and import it into my local. For a site that doesn't change on the live side, you can simply export from your local and import it back to the live site. In the real world, this isn't always possible. So anything you don on your local that affects the database (adding menu items, changing blocks, etc.) must be done by hand. There are tools for exporting content types and views, though, that make it a little easier. Worst case, you can take your live site offline for a hile in a maintenance window and do the reverse import. Nasty business, but nobody has found a foolproof solution.

The other problem is going to be your files directory. Some folks keep the files in version control, so they can be replicated in both directions. If you do this, identify your cache directories, and tell version control to ignore them. A difficulty with this involves file ownership. If the files created by your web server have the same owner as the code, it is possible to use version control or ftp to sync them. But if not, you're going to have to figure out a way with scripts to change permissions. Some larger sites use rsync or symlinks to share between multisites. Darn, I wish there was an easier way, but this is a topic unto itself.

10) Wrapping it up

There you have it; now go out and build something!

And don't forget to write things down.