Note: fabpress is in early development, use with caution

If you want to developp locally with Wordpress, you usually have to follow these steps:

• install a local copy of Wordpress
• import your production MySQL database
• search and replace permalinks in database (http://mysite.com to http://localhost/dev/mysite)
• install all your plugins and themes with correct versions
• download media files

Then, each time there is a change on production website and you need to pull these changes, you have to go through the same steps. And the same thing happens if you want to deploy your local website in production.

Going through these steps by hand is a nightmare and this is why I wrote fabpress: I wanted a command-line tool that would let me mirror a Wordpress installation via a single command.

What is fabpress ?

• a bunch of scripts, written in Python on top of Fabric and WP-CLI, two awesome tools
• a way to pull/push database, media files, themes, plugins from/to your production wordpress website
• a command-line tool, tested on ArchLinux and Debian, that could probably work on Mac OS and other Linux distributions
• free (as in free speech and free beer), open-source, licensed under BSD

What is not fabpress ?

• production-ready. I use it on my projects, and it works. There is absolutely no warranty it will work for you, with your setup. Before trying it, please, backup your data. I mean it, seriously.

Requirements

On local machine

• Python 2.7
• Fabric for managing connexion to server and calling commands

On remote machine

• SSH access

On both

• WP-CLI for dealing with most of the Wordpress stuff
• A Linux system (fabpress was developped and tested on Archlinux and Debian Wheezy)

Installation

Recommanded installation procedure requires pip, but you can also use easy_install. Please install pip before continuing.

Fabric

Install Fabric your local machine:

sudo pip install fabric

WP-CLI

Follow the procedure detailed on WP-CLI website, on your local and production machines.

Fabpress

Fabpress is available on PyPi. Install it on your local machine:

pip install fabpress --user

This method will also download and install Fabric

Configuration

First, move into your project directory:

cd /home/user/projects/mysite

Create a fabfile.py file:

echo 'from fabpress import tasks as fp' >> fabfile.py

Then, generate a config file:

fab fp.config.create

This will create a fab_settings.py file in your project directory. Fell free to add it to your VCS ignored files.

You can now edit the file (it is heavily commented):

nano fab_settings.py

Import your settings in your fabfile.py:

echo "import fab_settings" >> fabfile.py

After that, well, you're almost good to go. Remember to create a MySQL database for your local instance.

A bit of theory

Tasks

A task is an action you can run from command line, using the following notation:

fab command:argument1=value,argument2="value"

# Quotes and arguments name are not mandatory
fab command:value1,value2

# Some tasks just don't need arguments
fab command

You can list available commands via fab -l and get additionnal informations about a fabpress task, with fab fp.<command_name>:help.

Targets

In fabpress, many tasks can be run independantly on remote or local Wordpress instance. For exemple, take the following tasks:

fab fp.db.sync:local
fab fp.db.sync:remote

The first one will create a backup of your remote database, download it and import it into your local wordpress instance. The second one will do the opposite: backup your local database, upload it and import it into your remote instance.

When a task require a target argument, which value can be either remote or local, it usually means data (database, media files, plugins, themes...) will be imported INTO your target wordpress instance. Some tasks do not import data, but still require a target: fab fp.db.reset:<target> will reset all database tables of targeted installation.

Note that fabpress help and documentation sometimes mentions origin. This term is a shortcut for designating the opposite of a target. With the following command fab.main.sync:local your target is local, and origin is your remote installation, from where data will be imported.

If you run fab.main.sync:remote, origin designate your local Wordpress instance.

Example workflow

First, we move to our project directory:

cd /home/user/projects/mysite

Let's mirror the production website, so we can use it locally:

fab fp.main.mirror:local

# typical output

This is an important choice. Do you want to continue ? [y/N] y
Running main.mirror [on local]...
    Running base.collect_data [on remote]...
    Running main.download [on local]...
        Changing permissions of /var/www/mysite to 770
        wp-config.php was copied from sample. Do you want to edit it ? [Y/n] y
        Edit your file located at /var/www/mysite/wp-config.php then relaunch this command

fab fp.main.mirror:local
This is an important choice. Do you want to continue ? [y/N] y

Existing wp-config.php file found
    Running main.sync [on local]...
        Syncing databases (from remote to local)
            Running db.export [on remote]...
            Running db.import [on local]...
                Creating a safety backup of local database, juste in case
                Downloading backup from remote
                Importing backup.sql into local database...
                Deleting useless SQL backups...
        Running db.fix_permalinks [on local]...
            Updating URL(s) from mysite.com to localhost/mysite...
        Running theme.sync [on local]...
            Skipping theme blast: it is listed in ignored_themes
        Running plugin.sync [on local]...
            Running media.sync [on local]...
        Syncing media files from remote to local (please, be patient, this may take some time)
Done.

We can now open http://localhost/mysite with any web browser, and browse the local copy of our production website. If you encounter 404 errors, login at http://localhost/mysite/wp-admin and update your permalinks (Settings > Permalinks). You should not have to do it again after that.

Then, it's time to work. We install themes, plugins, create new pages and posts, import media files...

When we're done and want to push your local changes in production, we just run:

fab fp.main.push

Later, if we want to import changes from production:

fab fp.main.pull

Hooks

Sometimes, you want to do something when a task is run. For example, pulling from your theme's Git repository when you run fp.theme.sync on your remote installation. Hooks are here for that:

# hooks.py (create this in the same directory as your fab_settings.py)

from fabric.api import run, cd
def pull_theme():
    with cd("/var/www/mysite/wp-content/themes/mytheme"):
        run("git pull")


# fab_settings.py

import hooks

remote = {

    # ...

    "hooks": {
        "theme.sync": hooks.pull_theme
    },
}

Available tasks

Output from fab -l:

fp.config.create         Create a config file from fabpress sample
fp.db.clear_backups      Remove backup files on target
fp.db.export             Export the database from target installation to the given path
fp.db.fix_permalinks     Search and replace all occurence of origin domain with target domain
fp.db.import             Import the database dump at origin path to the target
fp.db.reset              Delete all tables in target database
fp.db.sync               Sync target database with origin, replacing origin permalinks with target permalinks
fp.fs.drop               Remove all files of target, including target directory
fp.main.download         Download at target a copy of origin Wordpress files (version and languages preserved)
fp.main.drop             Delete target files and database. Will also delete the installation parent directory.
fp.main.help             Get some help
fp.main.mirror           Create at target an exact mirror of origin wordpress installation
fp.main.pull             Sync database, themes, plugins and media files from remote to local installation
fp.main.push             Sync database, themes, plugins and media files from local to remote installation
fp.main.sync             Pull origin database, themes, plugins and media files to target
fp.main.wp               Run a wp-cli command on the target. You don't need to prefix it with 'wp', it will be added automatically
fp.media.sync            Download origin media files to target
fp.plugin.sync           Download and activate origin plugins on target
fp.theme.sync            Download and activate origin themes on target

Limitations

• For some reasons, when mirroring a Wordpress installation for the first time, you'll have to manually save the permalinks from the admin, in order to load Custom Posts Types permalinks. Else, accessing a CPT detail page would raise a 404.
• Will only download Themes and Plugins that are available on wordpress.org.

To-do list

• sync wordpress versions
• add support for more than two targets

Changes

0.1.1 - 29/10/2014:

• Syncing DB now clear transients, which should fix some URL issues with plugins (such as Polylang)

0.1 - 29/09/2014:

• initial release

Contribute

Contributions, bug reports, and "thank you" are welcomed. Feel free to contact me at <contact@eliotberriot.com>.

License

The project is licensed under BSD licence.