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, Vagrant, VVV and 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.
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install mysql
brew install wget
brew install node
npm install -g grunt-cli
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. If you don't, ask someone else on the team to ask VIP to add you.
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.
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.
- 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.
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
First download the latest backup from VaultPress.
- Go to 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/
- Search and 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.
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.
To work on the site, you'll want to review the git workflow docs 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/.