## Setup

To work on this project locally, you'll need to do the following:

- Make sure you have a couple prereqs installed on your computer
- Install [Virtualbox](https://www.virtualbox.org), [Vagrant](https://www.vagrantup.com/), [VVV](https://github.com/Varying-Vagrant-Vagrants/VVV) and [VV](https://github.com/bradp/vv)
- Create a new WP site using VV
- Download a copy of the live site's db and add it to our local site.
- Install a couple VIP specific things
- Start working on the site

Note that it is not yet possible to get a partial download of uploaded images from production via VaultPress. But they're working on it. If you need images to work locally, you'll likely have to download just the ones you need and add them manually.

### Prereqs

#### homebrew
```
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```

#### mysql and wget
```
brew install mysql
brew install wget
```

#### node + grunt-cli
```
brew install node
npm install -g grunt-cli
```

#### github

Check for existing ssh keys
```
ls -al ~/.ssh
```

if not found, do:
```
ssh-keygen -t rsa -b 4096 -C "your_email@motherjones.com"
Enter a file in which to save the key (/Users/you/.ssh/id_rsa): [Press enter]
Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]
```

add new/existing key to ssh-agent
```
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
```

copy key to add to github
```
pbcopy < ~/.ssh/id_rsa.pub
```

follow instructions at https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/

```
git config --global user.name "FIRSTNAME LASTNAME"
git config --global user.email yourname@motherjones.com
```

**Important:** Make sure you have permissions for the site repo at [https://github.com/wpcomvip/motherjones](https://github.com/wpcomvip/motherjones). If you don't, ask someone else on the team to ask VIP to add you.

### Setup Virtualbox, Vagrant + VVV

See: https://github.com/Varying-Vagrant-Vagrants/VVV/blob/develop/docs/en-US/index.md

Install Virtualbox: https://www.virtualbox.org/wiki/Downloads

Install Vagrant: https://www.vagrantup.com/downloads.html

If you already have Vagrant, use `vagrant -v` to make sure you're running a recent version.

```
vagrant plugin install vagrant-hostsupdater
vagrant plugin install vagrant-triggers
vagrant plugin install vagrant-vbguest
```

```
git clone git://github.com/Varying-Vagrant-Vagrants/VVV.git vagrant-local
cd vagrant-local
git fetch
git checkout master
```
Run `vagrant up` and then check http://local.wordpress.dev/ to make sure we're good so far.

#### Install VV
see: https://github.com/bradp/vv#os-x-installation

```
brew install bradp/vv/vv
```

(optional: enable tab completion)
add `source $( echo $(which vv)-completions)` to the end of your .bash_profile, .bashrc or .zshrc.

#### Increase the server memory for your virtual machine
- Use the command line to navigate to the root directory of your Vagrant box (where your Vagrantfile is located).
- Paste the following command into your terminal, hit Enter, and then type Control-D.

```
cat > Customfile
config.vm.provider "virtualbox" do |v|
  v.memory = 2048
  v.cpus = 4
end
```
- That created a new file, Customfile which increases the memory limit on your Vagrant box, as recommended in the VVV documentation.

### Set up the box for this site
```
cd www
vv create
```

You'll then see a series of prompts. Respond thusly:

Prompt | Text to enter
------------ | -------------
Name of new site directory: | mjwp
Blueprint to use (leave blank for none): | *hit [Enter]*
Domain to use (leave blank for mjwp.dev): | mjwp.dev
WordPress version to install (leave blank for latest version or trunk for trunk/nightly version): | *hit [Enter]*
Install as multisite? (y/N): | n
Git repo to clone as wp-content (leave blank to skip): | git@github.com:wpcomvip/motherjones.git
Local SQL file to import for database (leave blank to skip): | *This filename must be an absolute path, so the easiest thing to do on a Mac is to drag your mysql file into your terminal window here: the absolute filepath with fill itself in. Absolute filepaths begin from `/` and go all the way to the file. If you don't have a SQL file you can skip this step and we'll load it later*
Remove default themes and plugins? (y/N): | y
Add sample content to site (y/N): | N
Enable WP_DEBUG and WP_DEBUG_LOG (y/N): | N

After reviewing the options and creating the new install (you'll be prompted part way through the install process to provide your admin password), proceed on with the following steps.

**NOTE:** recent reports indicate that sometimes vv will not correctly download and install WordPress. If this happens to you, you can run `wp core download` from the root directory of the WP install and then visit http://mjwp.dev in the browser to complete the WP installation.

Vagrant expects the following for the database settings:

```
db: mjwp
user: wp
pass: wp
host: localhost
```

### Prepare and load the database

First download the latest backup from VaultPress.
- Go to [https://dashboard.vaultpress.com/](https://dashboard.vaultpress.com/) (you should already be logged in if you're logged into the website, if you don't have permission to access VaultPress, ask another team member to ask VIP to add you).
- Click on **Backups** and then under the list of recent backups, select the most recent one (or the one you want to use locally) and click on **View Backup**.
- At the top of the next page you'll see a **Download** button, click on it and uncheck the boxes for everything except **Database**.
- This will prepare a download and notify you when it's ready.

Once you have the database downloaded, find the zip file on your computer and open/uncompress it.

You'll see that there is a folder called **sql**.

In your terminal, cd to that folder and we're going to combine all of the sql files into one big sql dump.

From that folder, you can do this by running: `cat *sql > mysql.sql` where mysql.sql is the destination file.

Move the new combined sql file to the wp-content folder of your WP install.

Now we have to ssh into the vagrant box to load the db and perform a search and replace.

We'll use a couple WP-CLI commands to do this:
- Load db [https://developer.wordpress.org/cli/commands/db/import/](https://developer.wordpress.org/cli/commands/db/import/)
- Search and replace [https://developer.wordpress.org/cli/commands/search-replace/](https://developer.wordpress.org/cli/commands/search-replace/)

So, to start, from your terminal window, make sure you're back in the root folder for your local WP site and run:

```
vagrant ssh
cd ../../vagrant/www/mjwp/htdocs/wp-content
```

And then:

```
wp db import mysql.sql
wp search-replace 'http://www.motherjones.com' 'http://mjwp.dev' --skip-themes --skip-plugins
```

You're done working on the vagrant box and can run `exit` to close your ssh connection.

### Add VIP Go MU Plugins

Finally, we have to add a few plugins required by the VIP Go environment. See steps 3 and 4 here: https://vip.wordpress.com/documentation/vip-go/local-vip-go-development-environment/.

If you're still in the root directory of your WP install, run:

```
git clone git@github.com:Automattic/vip-go-mu-plugins.git --recursive wp-content/mu-plugins/
```

Or just make sure the contents of that repo are cloned into the mu-plugins directory and then cd into that directory and run:

```
git pull origin master
git submodule update --init --recursive
```

Just to make sure everything is up to date. VIP recommends doing that periodically just to make sure you have the latest versions of everything. Do not commit the VIP plugins directly to our site repo (they should be excluded already by .gitignore).

Now we need to actually load these plugins. To do that, open the wp-config.php file in the root of your WP install and add the following:

```
if ( file_exists( __DIR__ . '/wp-content/vip-config/vip-config.php' ) ) {
    require_once( __DIR__ . '/wp-content/vip-config/vip-config.php' );
}
```

Just above the line that says `/* That's all, stop editing! Happy blogging. */`

That's it! You should now see the site at http://mjwp.dev.

### Work on the site

To work on the site, you'll want to [review the git workflow docs](https://github.com/RobertWise/mjwordpressdocs/blob/master/git-workflow.md) to make sure you have a handle on how to submit changes.

You'll also want to make sure you're set up to run grunt tasks to compile CSS, minify JS, etc. if that's relevant to the changes you're making.

To do that, cd into the theme folder (from the root of the WP install, that's: wp-content/motherjones). Then run:

```
npm install
```

To make sure you have all of the various node modules you'll need (defined in package.json).

Once that stuff is installed, you'll be able to run `grunt watch` which will automatically compile the css anytime you make a change to any of the scss files.

To minify JS you can run `grunt uglify`.

To see what other grunt tasks are available, you can look at the theme's gruntfile.js and review the docs for grunt at https://gruntjs.com/.