Metadata-Version: 1.1
Name: fabpress
Version: 0.1
Summary: Wordpress local installation and deployment made simple
Home-page: https://github.com/EliotBerriot/fabpress
Author: Eliot Berriot
Author-email: contact@eliotberriot.com
License: BSD
Description: 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 <http://www.fabfile.org/>`_ 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 <http://www.fabfile.org/>`_ 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 <http://pip.readthedocs.org/en/latest/installing.html>`_, but you can also use ``easy_install``. Please install pip before continuing.
        
        Fabric
        ******
        
        Install `fabric <http://www.fabfile.org/installing.html>`_ 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 via ``pip``. 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' >> /home/user/projects/blast/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.
        
        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.
        
        
        Changes
        =======
        
        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.
        
        .. _Fabric: http://docs.fabfile.org
        .. _WP-CLI: http://wp-cli.org/
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
