WP Snapshots

A project sharing tool for WordPress.

Table of Contents

• Overview
• 2.0 Upgrade Notice
• Installation
  • Windows-specific Installation
• Configure
• Usage
• Identity Access Management
• Troubleshooting

Overview

WP Snapshots is a project sharing tool for WordPress. Operated via the command line, this tool empowers developers to easily push snapshots of projects into the cloud for sharing with team members. Team members can pull snapshots, either creating new WordPress development environments or into existing installs such that everything “just works”. No more downloading files, matching WordPress versions, SQL dumps, fixing table prefixes, running search/replace commands, etc. WP Snapshots even works with multisite.
WP Snapshots stores snapshots in a centralized repository (AWS). Users setup up WP Snapshots with their team’s AWS credentials. Users can then push, pull, and search for snapshots. When a user pushes a snapshot, an instance of their current environment (wp-content/, database, etc.) is pushed to Amazon and associated with a particular project slug. When a snapshot is pulled, files are pulled from the cloud either by creating a new WordPress install with the pulled database or by replacing wp-content/ and intelligently merging the database. WP Snapshots will ensure your local version of WordPress matches the snapshot..
A snapshot can contain files, the database, or both. Snapshot files (wp-content/) and WordPress database tables are stored in Amazon S3. General snapshot meta data is stored in Amazon DynamoDB.

Upgrade

WP Snapshots 2.0+ allows users to store database and files independently. As such, some snapshots may only have files or vice-versa. Therefore, WP Snapshots pre 2.0 will break when attempting to pull a 2.0+ snapshot that contains only files or database. WP Snapshots 2.0 works perfectly with older snapshots. If you are running an older version of WP Snapshots, you should upgrade immediately.

Install

WP Snapshots is easiest to use as a global Composer package. It’s highly recommended you run WP Snapshots from WITHIN your dev environment (inside VM or container). Assuming you have Composer/MySQL installed and SSH keys setup within GitHub/10up organiziation, do the following:
Install WP Snapshots as a global Composer package via Packagist:

composer global require 10up/wpsnapshots

If global Composer scripts are not in your path, add them:

export PATH=~/.composer/vendor/bin:$PATH

If you are using VVV, add global Composer scripts to your path with this command:

export PATH=~/.config/composer/vendor/bin:$PATH

Configure

WP Snapshots currently relies on AWS to store files and data. As such, you need to connect to a “repository” hosted on AWS. We have compiled instructions on how to setup a repository on AWS.

• wpsnapshots configure [–region] [–aws_key] [–aws_secret] [–user_name] [–user_email]
  This command sets up WP Snapshots with AWS info and user info. If the optional arguments are not passed
  to the command, the user will be promted to enter them, with the exception of region which will default to
  us-west-1.
  Example Usage With Prompts :

  wpsnapshots configure 10up
  

  <p>
    <strong>Example Usage Without Prompts (No Interaction) :</strong>
  </p>
  
  <pre class="notranslate"><code>wpsnapshots configure yourcompany --aws_key=AAABBBCCC --aws_secret=AAA111BBB222 --user_name="Jane Smith" --user_email="noreply@yourcompany.com"
  

If WP Snapshots has not been setup for your team/company, you’ll need to create the WP Snapshots repository:

wpsnapshots create-repository <repository>

If a repository has already been created, this command will do nothing.

Usage

WP Snapshots revolves around pushing, pulling, and searching for snapshots. WP Snapshots can push any setup WordPress install. WP Snapshots can pull any snapshot regardless of whether WordPress is setup or not. If WordPress is not setup during a pull, WP Snapshots will guide you through setting it up.
Documentation for each operation is as follows:

• wpsnapshots push [] [–exclude_uploads] [–exclude] [–scrub] [–path] [–db_host] [–db_name] [–db_user] [–db_password] [–verbose] [–small] [–slug] [–description] [–include_files] [–include_db]
  This command pushes a snapshot of a WordPress install to the repository. The command will return a snapshot ID once it’s finished that you could pass to a team member. When pushing a snapshot, you can include files and/or the database.
  WP Snapshots scrubs all user information by default including names, emails, and passwords.
  Pushing a snapshot will not replace older snapshots with the same name. There’s been discussion on this. It seems easier and safer not to delete old snapshots (otherwise we have to deal with permissions).
  --small will take 250 posts from each post type along with the associated terms and post meta and delete the rest of the data. This will modify your local database so be careful.
• wpsnapshots pull [–path] [–db_host] [–db_name] [–db_user] [–db_password]…