HOWTO use rsync to deploy WordPress sites to WebFaction

These days I’m spending a lot of time developing a WordPress-powered site, not yet online at the time of this writing. My workflow is simple: I develop at my home box (Mac OSX + XAMPP + Komodo Edit + Sequel Pro, thank you very much), and from time to time I deploy to a private URL hosted with WebFaction, where the rest of the project’s team can check for updates, give opinions, etc.

First I tried using a private Subversion repository, but it choked every time WordPress -or any plugin!- was updated, so in the end rsync proved to be the right tool for the job. I wrote these instructions on how to do this deployment mostly for myself, but I thought ’someone out there’ could benefit from them as well, so here we go. You’ll thank me later.

IMPORTANT: while this HOWTO applies directly to WebFaction customers only —and you should give them a try if you’re considering switching hosting companies, they’re great— resourceful Web boys and girls will surely know how to make it work at their Web company of choice too.

Requirements

• A fantastic WordPress-powered Website running on your box, itching to be deployed.
• The rsync command line tool running on your local box. Normally built-in with Linux or Mac OSX, I guess it should work under cygwin as well, but I haven’t tried.
• A way to export your MySQL database. I use Sequel Pro, but phpMyAdmin or mysqldump if you’re hardcore, will do just as well.
• Your favourite text editor. I prefer vi, because I’m old.
• An account with WebFaction. Any plan will do, since we only need SSH login and their Control Panel.

Step by step

Start by going to your WebFaction control panel, and create a new Static/CGI/PHP Application. Call it myproject, and hit Create. It’s up to you to wire it to one of your domains, so I won’t touch on that here.

Now fire up a terminal session at your home box, change to your project’s root directory, and type:

cp wp-config.php wp-config.php.tmpl

Now paste the following line into a new file called rsync_exclude.txt, which will live at the same directory:

wp-config.php

The previous two commands will make sure your local configuration settings will not overwrite those in the production environment every time you rsync.  Now we’re ready to invoke rsync’s magic:

rsync -avzh --delete --exclude-from '/path/to/local/wordpress/rsync_exclude.txt' . YOURUSERNAME@YOURBOX.webfactional.com:/home/YOURUSERNAME/webapps/myproject

This command does the following:

• It mirrors the exact state of your local development root directory with your live site at WebFaction, adding, modifying and deleting files as needed. Exercise good-old common sense while running this line, OK? (if you’re not too sure, add the -n parameter, which asks rsync to do a ‘dry run’ only, without changing anything at the destination site).
• The -avzh instructs rsync to process all hard links, preserve file attributes and other niceties, use compression for faster transfers, and display human-friendly statistics.
• The –exclude-from switch does what you expect: tells rsync to skip what’s listed on rsync_exclude.txt, which is nothing but WordPress’ local configuration settings (the wp-config.php file).
• The last two parameters describe the source and target directories to sync. The single dot (.) means “the current directory I’m in”, and the target directory is actually a combination of a SSH-enabled host plus the full path, separated by a colon. rsync will ask for your SSH password, so don’t worry about that.

Almost ready now!

Log into your box using SSH, change to ~/webapps/myproject, and execute:

cp wp-config.php.tmpl wp-config.php

Now go and edit wp-config.php and change the database connectivity options (DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, and maybe DB_CHARSET and/or DB_COLLATE) to reflect your production environment. Which reminds me…

What about the database?

The method outlined above takes care of the PHP side of things only. If you’re also producing content at your home development box, as I am, you’d like to copy your database over to the production environment as well. And rsync can help here too.

Using your MySQL frontend of choice, connect to your local host and dump your project’s full database to a file with a .sql extension (use today’s date as part of the the filename, it’ll help). If you’re using Sequel Pro, go to File -> Export -> MySQL dump and you’re set. Save the dump file with the rest of the stuff at your project’s root directory, and rsync will catch it next time.

If you develop locally using “localhost” or “myproject.local” as your home URL, as most of us do, you will have to edit the dump file and replace all local URLs with “live” URLs. If you use vi, this is a one-liner:

:1,$ s/myproject.local/myproject.com/g

(That means in oldfartese “change all the occurrences of the string myproject.local into myproject.com”)

Do a rsync now, watch your dump file get copied, and SSH to WebFaction.  We’re going to run one command that will overwrite your production database with the contents of the SQL dump file you just rsync’d. Which means you will not do this once your Website is live, unless you’ll have an excellent reason to do so. For the purposes of this example, “latest.sql” will be the dump file, and the production MySQL database will be “xyuser_myproject”. The command to run (at ~/webapps/myproject/) will be:

mysql --user=YOUR_SQL_USERNAME --password=YOUR_SQL_PASSWORD xyuser_myproject < latest.sql

And that’s all folks! You should now point your browser to your live WebFaction URL, and see your updated WordPress-powered Website. Now wasn’t that easy!

Conclusion / Everyday use

Now that I look back at all those scary paragraphs and lines of code, I’d like to say that for everyday use, this solution is actually pretty straightforward. It’s a matter of firing up Sequel Pro, exporting, running sync.sh (which is nothing but a wrapper shell script that invokes the rsync line), and SSH’ing to WebFaction to import the data back in. With a bit of extra shell script-fu, I’m sure you could streamline the process even more, let’s say to bypass Sequel Pro and to everything with MySQL built-in command line tools.

So, what do you think? Did this article help you? Found any bugs? Anything doesn’t work? Drop a line at the comments!

UPDATE: big thanks go to Japh for his help in simplifying this tutorial. Isn’t the Internet a great thing?

Tagged as: Development, PHP, rsync, WebFaction, WordPress