Separating your files from Drupal's, and simplifying upgrades

Drupal's developers are constantly fixing bugs and striving to make our Drupal installations as safe as possible - there have been 6 security updates of the 5.x and 6.x branches so far in 2008. If you have several sites, the maintenance work can really cut into your time.

I'd like to share with you a little trick I use in my server setup to streamline the upgrade process when a new core release is available. It not only makes core updates quicker and safer to implement, it also leaves the previous version ready to use on my server in case there are problems with the new Drupal core version.

My setup involves keeping the sites directory outside of the main Drupal installation and using symlinks to tell Drupal where it is. This saves me the step of copying the directory from one Drupal installation to the next when upgrading, which can be time consuming and a potential source of problems on a content-rich site.

Notes on terminology

Anything I refer to in [square brackets] requires you to substitute your own filenames or paths as required: [docroot], [drupal-tarball-name], etc.

In a nutshell:

• I don't keep the /sites directory in the Drupal-standard location in the [docroot] directory, shown here:

  

• I keep the /sites directory outside of [docroot] and tell Drupal where it is using a symbolic link.

  A "symlink" is a file that contains a reference to another file or directory (an absolute or relative path). Programs can read or write to files named by a symbolic link as if they were operating directly on the target file. Unlike normal, "hard" links, symbolic links can point to directories, not just files.

  

You need the command line

Setting this up requires command line (aka "shell") access to your server. Unfortunately, if you only have access to your website's code via FTP or a CPanel-like client interface, you cannot set up symbolic links.

The First Time

Here's where I make things easier for the future. I normally have to copy my [docroot]/sites directory to the new code base every time I do an update. As long as I am dealing with a newer version that uses the same files and structures, I can save myself that step and give /site directory a permanent home outside of the Drupal installation itself.

1. Login to your server on the command line and enter your password when asked to:

   ssh -l username example.com
   

2. Navigate to the directory containing [docroot] - remember, this might be /var/www, /web/loc - it depends how your server is set up:

   cd /path/to/directory
   

3. Move the /sites directory from [docroot] to the server's root. In this case, I just navigated to the root level, so I use ".", which means "here" for commands like this:

   mv [docroot]/sites .
   

4. Symlink from Drupal to the /sites directory - Your Drupal installation now needs to know where to find the sites directory now that you have taken it from where it is supposed to be. Replace it with a symbolic link (symlink) called "sites" that points to the directory in its new location and Drupal will never know the difference.

   ln -s /path/to/sites /path/to/[docroot]/sites
   

   That is:

   • ln -s - MAKE A SYMBOLIC LINK
   • /path/to/sites - WITH THIS TARGET
   • /path/to/[docroot]/sites - IN /var/www/[docroot] CALLED 'sites'

Fast Updates to the Drupal Core

The good news is, once your site installation is set up this way, changing versions of Drupal becomes a matter of changing two directory names and one symlink. You never have to move your sites directory around or copy it into a new installation - all your content, non-core modules, and themes will remain the same (and in the same place) when you change between versions. This is especially nice if you have to roll back to an older version after having created new content or theming changes!

With this structure in place, the core update procedure works like this:

1. Make a backup of your site's database. You will need this if you have to roll back your update for any reason. It is generally a good idea to make a backup of your site's files and database regularly, but especially so before making major changes.

2. Get and unzip tarball of latest Drupal release to your root directory:

   1. Copy the location of the Drupal or Acquia Drupal release you want to install from http://drupal.org/project/Drupal+project or http://acquia.com/downloads. This is a link to a tarball file, called something like http://ftp.drupal.org/files/projects/drupal-6.xx.tar.gz or http://acquia.com/files/downloads/acquia-drupal-1.x.x-ISR.1234.tar.gz.

   2. Login to your server and navigate to the directory containing [docroot]:

      ssh -l username example.com
      cd path/to/directory
                  
      

   3. Download and extract ("untar") the Drupal release, making (in this example) a directory called "[new-drupal-release]":

      wget http://ftp.drupal.org/files/projects/[new-drupal-release].tar.gz
      tar -zxvf [new-drupal-release].tar.gz
                  
      

3. Remove the "sites" directory from the new Drupal installation:

   rm -r [new-drupal-release]/sites
           
   

4. Replace it with a symlink to the relocated "sites" directory:

   ln -s /var/www/sites /var/www/[new-drupal-release]/sites
     
   

5. Change the name of the old [docroot] directory to [docroot]_old:

   mv [docroot] [docroot]_old  
   

   This is now a backup of your working site on the previous version of the Drupal code base. Keep it and a copy of your database backup (you did keep a backup of the db, right?) in case you encounter problems with the new version of Drupal and need to get your site back online in a hurry.

6. Change the name of the new Drupal directory to [docroot]:

   mv [new-drupal-release] [docroot]
   

7. Run update.php to update your site's database structures to those needed by the new release by navigating to http://example.com/update.php in the browser and following the update instructions.

Rolling back an upgrade

If you have any problem with a new version, you can switch back to the old version without reconfiguring, copying, or worrying about your content and theming:

1. Make a new database using that backup you made (the update that went through the failed update process is unfortunately unusable).
2. Change the database connection in /sites/default/settings.php to match the new database name.
3. Rename [docroot] to [docroot]_update_gone_wrong and [docroot]_old back to [docroot].

Your site should now be up and running again on the older code base, giving you time to solve whatever problems you encountered with the update process.

Keep backups

Don't delete your old [docroot] directories until you are sure everything is okay. You can even keep the last two versions on your server, just in case, and delete [docroot] directories that are more than two updates old. Be sure to keep your backup database copies, too!

Whew!

That might look like a lot on the face of it, but I have my core updates down to a couple of minutes with this setup and I hope it will bless your days with extra minutes for the important stuff, like coffee ...

Summary

Setup

1. Move the [docroot]/sites directory to the root level of your server.
2. Symlink to it from [docroot]
3. If it all works, make backups of your site's code, content and database.
4. Have coffee.

Updates

1. Get and extract new Drupal or Acquia Drupal version tarball into your server.
2. Delete the /sites directory from the new version.
3. Add a symlink to the new Drupal directory pointing at your /sites directory.
4. Did you make backups of your site and database? It's working now, you know ...
5. Rename "[docroot]" "[docroot]_old" and the new Drupal directory "[docroot]".
6. Run the database update script, update.php.
7. Have coffee.