Here’s how to get started with a new WordPress project that’s hosted an WP Engine, an *excellent* hosting platform that was designed specifically to work with WordPress.
Here’s what we’re going to cover in this post:
- Setting up a new WordPress installation on WP Engine that works with Git.
- Setting up your new installation to work with Git on your computer.
- Setting up MAMP to allow you to develop locally and push updates to Production (or Staging) via Git.
- The workflow once you’re all set up.
Setting up a new WordPress installation on WP Engine
If you don’t already have an account with WP Engine, go to their pricing page and sign up for a Personal account. It may seem a little expensive vs. other WordPress hosting services, but trust me, it is totally worth it. Being able to use Git is huge.
Once you have an account, you can set up a new WordPress installation (i.e. “install”) by going to your WP Engine dashboard and clicking the “+ Add Install” button (should be pretty obvious). WP Engine will then set up your new install and email you when it’s done (it only takes minutes). Log into the WordPress dashboard via the URL they send you (which should be in the format of http://your_application.wpengine.com) and adjust the name of your site and your name and email address as you’d like.
Setting up your new install to work with Git
Out of the box, your new WordPress install will not be able to work with Git – you must request that WP Engine set up git push for your application in order to get this going. You do this by going to WP Engine’s support site and submitting a request that includes the following info:
- Your account name. You may have access to multiple WP Engine accounts if you’re developing sites for clients, and they’re paying the monthly hosting bill. That is, you’ll need to have separate accounts for each client if you’d like the billing to be separate. If you’re going to be paying the monthly hosting bill yourself and passing along the hosting costs to clients (this would allow them to save some money if you have more than 3 clients), then you may be able to maintain a single account. Either way, just include your account name in your request so there’s no question.
- Your install name. I.e. the name of the new install you set up above.
- Your SSH public key. If you don’t have one of these, GitHub has some great instructions on how to set one up over here: Generating SSH Keys. Once you have an SSH public key, include it in your request to WP Engine.
WP Engine will then let you know when your install has been set up to work with Git. This typically takes a few hours, but it could take a day or so depending on when you submit the request (on a weekend, etc.).
Note that “install” = “application” in these instructions and in WP Engine. Your install is an application so these two words are interchangeable.
Confirming access to the “git remotes” for your new application
Once your application has been set up to work with Git, the first thing you need to do is confirm that you can access it. You do this by opening up Terminal (on a Mac), cd-ing to your websites directory (~/Sites in my case), and typing the following command:
$ cd Sites
$ ssh email@example.com info
If you’re doing this for the first time, check out the “Confirm access” section of this WP Engine Getting Started with Git page. You’ll need to confirm that you want to connect to git.wpengine.com (they’ll be permanently added to your list of known hosts).
If you’ve already added git.wpengine.com to your list of known hosts, then typing the command above should print out “hello [your ssh pub key name]” and then list the repositories you can push to, which should include the new application you just requested.
If you don’t see your new application listed, then it’s not set up properly and you should reach out to WP Engine Support.
Setting up your local code repository
Note that WP Engine’s set up instructions are very good – I’ve just simplified and taken some of the thinking out of the process below.
Setting up the local repository for all of the files in your new WordPress installation is as easy as downloading a zipped copy of your install from the WP Engine website. Just go to your account dashboard, click on your application, and then click up the “Backup Points” link in the left sidebar. This will take you to a list of backup points, and all you have to do is download your latest checkpoint. Unzip the downloaded file, rename it to match the name of your application on WP Engine), and save it wherever you save your existing websites on your computer.
Open up the folder you just unzipped and delete the .git folder (this one may not be there, which is fine) and .gitignore file in this folder (you’ll be re-creating them in a second, but these files have a bunch of history that you don’t need to store in Git – it’s better to delete these files and start fresh). Note that since these files start with a “.”, they’ll be hidden from view by default. In order to see them and delete them in the Mac Finder window, you’ll need to show hidden files, which you can do via these instructions from lifehacker: Show hidden files in Finder.
Once these files have been deleted, you’ll need to add them back. WP Engine gets you started witha starter .gitignore file here on their website. Choose the second one that IGNORES WordPress core files (rename it “.gitignore” when you download it). You don’t need to track changes in the core WordPress files because you shouldn’t be making any changes to them, and you’ll want to be able to upgrade your version of WordPress via the WordPress admin dashboard whenever they roll out an update.
In order to create a new .git folder, you need to run some commands in Terminal:
$ cd ~/sites/your_application
$ git init .
Where “sites” is the name of the folder / directory (“folder” = “directory” by the way) where your new application (named “your_application” above) is stored. The second commands creates a .git folder within your application where all of the changes you make to the application files will be saved.
You then need to add all of the files that you downloaded from the WP Engine website a little while ago to Git, which you do by typing this:
$ git add . –all
Now this is where WP Engine’s Getting Started with Git instructions get really good so you should just follow those. Head down to the “Making the first commit…” section of that page. Note that the init and add steps above are included there – you’re going to pick up where it says:
$ git commit -m “initial commit…”
Enter that in Terminal and then just follow WP Engine’s instructions on that page and the next one. You will need to set up ‘git remotes’ for your application and do your first ‘git push’ to complete the set up process. You may as well set up both a “production” remote and a “staging” remote per the WP Engine instructions while you’re at it since it’s very quick and the same process for each.
Note that in order to actually push to staging, you’ll need to create your staging environment in the WP Engine section of the WordPress admin interface. Just log into your WordPress application, click on the main WP Engine page, click on the Staging tab, and then click the “Copy site from LIVE to STAGING” button. Your staging environment will be created in a minute or two, and then you can go back to Terminal and execute your first push per the WP Engine instructions.
Once you do that successfully, head back here to continue the setup process.
Adding your application to Atlassian’s SourceTree Application
SourceTree is a fantastic code management tool from Atlassian. It allows you to use a Graphical User Interface or GUI for working with both Git and Mercurial (Mercurial, or hg, is another source code management system) – this is so you don’t have to use Terminal for working with Git repositories. Adding a new Git repository is simple in SourceTree. Just follow these steps:
- First, download SourceTree (it’s free) if you don’t have it already
- Open up your Bookmarks (View > Show Bookmarks or Command + B)
- Click on the Add Repository button in the top left
- Click on the Working Copy option – this is important (you’ve already “cloned” the repository by downloading the files directly from WP Engine’s website so you just need to create a Working Copy in SourceTree)
- Browse to your application, which should be recognized by SourceTree as a Git application
- Give the Bookmark a name (or just accept the one it gives you) and click the Add button
And that’s it – your application should now be set up in SourceTree. To verify this, double click the Bookmark for your application to open up the code management interface. You should see a “master” branch in the Branches section on the left, and if you click on master, you should see your first commit. If you don’t see this, then something must have gone wrong.
And now you’re done setting up Git for your new WordPress application, and you’re almost ready to start actually making changes to the code! Just one more step left…
Setting up MAMP for local development
So what’s the point of developing locally? There are a few BIG benefits:
- You can make changes that can only be seen on your computer by your eyes only.
- You don’t have to go through the time-consuming cycle of make changes, upload the changed files to your site via FTP, and refreshing the page in your browser – this take time when you have to do this on hosted server somewhere.
- You can work on stuff when you don’t have an Internet connection (because it’s all being done on your computer).
- It’s a heck of a lot faster (because of no. 2 mostly).
This is all because you’re using your computer as your own local server – so communicating with the sever is super fast and it’s totally private.
But you can’t just do this out of the box – you need to set up a server that can run PHP on your local machine. The article referenced below explains:
MAMP, which stands for Macintosh, Apache, MySQL and PHP, is an application that allows you to install a local server-type environment in order to construct websites that would normally require you be on a live server somewhere. Ever opened a contact form in a browser from your desktop and wondered why it doesn’t work? The server-side components cannot operate without (in this case) the PHP back end, and this is where MAMP comes in. By installing this application, we can have a virtual server locally as our development sandbox.
So here’s how to set up MAMP for local development (if you’ve already followed all the steps above related to WP Engine):
1. Download and install MAMP
Use the instructions from this excellent article: Developing WordPress Locally with MAMP. Once you have MAMP installed and set up as they suggest, come back here and continue with the instructions.
2. Setup a local database for your application via MAMP
WordPress is ultimately just a content management system sitting on top of a database so you obviously need to set up a database for local development (WP Engine does this for you on your actual website). Fortunately, MAMP makes this really easy.
- Open up the MAMP application you just installed.
- Click the “Start Servers” button to get it running. This will open the MAMP start page in your default browser.
- Click on the “phpMyAdmin” tab in the top menu.
- Click on a the Databases tab and then create a new database (match the name of the database to the name of your application in order to make things intuitive for yourself).
3. Update your wp-config.php file to work with MAMP
The wp-config.php file that you downloaded from WP Engine (which is found in your main application folder on your local computer) is currently configured to work with WP Engine’s servers, but you need to set it up to work with your local server (MAMP).
The best way to do this is to start with wp-config-sample.php file that a brand new WordPress install starts you out with. You can do this by downloading the latest version of WordPress and just grabbing the wp-config-sample.php, or you can keep a copy of wp-config-sample.php somewhere because this file doesn’t seem to have changed since 2010.
Note that you’ll be replacing the wp-config.php file that WP Engine uses on your local computer, but this is okay because Git ignores this file. That is, Git does not track changes in this file or push it to the production site when you do a commit. So the wp-config.php file that you’re using locally can be totally different from the one that WP Engine uses on the production site – and it has to be in order to be able to develop locally with MAMP.
Here are the changes you want to make to wp-config-sample.php:
- DB_NAME – change ‘database_name_here’ to the name of the database you just created in MAMP (this should be the name of your application, per above)
- DB_USER – change ‘username_here’ to ‘root’
- DB_PASSWORD – change ‘password_here’ to ‘root’
Here’s what it should look like BEFORE you make these changes:
And here’s how it should look AFTER you make these changes:
Once you’ve made these changes, close the file, and rename it wp-config.php. Then replace the wp-config.php file from WP Engine with this new file.
4. Install WordPress locally for this application
Point your local browser (I find that Firefox works best for this…Chrome seems to have some issues) to http://localhost:8888/your_application. This will take you to the WordPress installation page.
Fill out the fields, matching your settings on your production site wherever possible. Also uncheck the search engines checkbox at the bottom. Then click “Install WordPress.”
Once you’re in the dashboard, update your site settings and your user settings to further match your production site as needed.
Important Note: you will need to keep you site settings in sync between your production site and your local site. Any of the settings that are changed by the user in the admin interface are NOT tracked in Git (since these are changes to the WordPress database for your application, not in the application files themselves).
You should now be able to develop locally and see any changes you make to the files on your computer in more or less real-time (after refreshing the page, of course). Now we’ll talk briefly about how to push any changes you make locally to the production site.
Pushing local changes to your production website
Pushing changes to your production site is really easy when you’re set up with Git & SourceTree. SourceTree will automatically track any changes you make, and then you’ll have to “commit” them (via the “Commit” button in the image below). When you commit, you should include a short commit message in plain English that just tells the future you (and other team members) what you changed – these can be very helpful if you ever break anything and need to “revert back” to a previous iteration.
Once you commit, then you’ll need to push your committed changes to your production site, which you do via the “Push” button in SourceTree (again, pretty straightforward). SourceTree will give you a message box that tells you how this process is going and if it completed successfully. If it does NOT complete successfully, then you’ll need to troubleshoot. It could be a problem in one of the files you pushed (be sure to test everything locally before you push to production) or it could be a problem on the WP Engine side. If you can’t figure it out, reach out to WP Engine Support – they’re super helpful.
I’m not going to get into using Git with teams (branches, etc.) because a lot of other people who understand that stuff a lot better than I do have written a lot about that. Here’s the most helpful article on that topic that I’ve come across: A successful Git branching model – this is the approach we use on the team projects I’m working on.
And that’s a wrap…
Sheesh…that was a long post. Took me a while to figure all of this stuff out so I hope you find it helpful. I know I will as I will inevitably forget pieces of this along the way…